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Managing SysV System Software describes system administration in the SysV environment. 
We’ve organized this manual as follows: 



Chapter 1 
Chapter 2 

Chapter 3 

Chapter 4 
Chapter 5 
Chapter 6 
Chapter 7 
Chapter 8 
Chapter 9 
Chapter 10 
Appendix A 



Is an introduction to system administration in the SysV environ- 
ment and a description of changes in Software Release 10 (SR10). 

Describes how to maintain nodes and provide services, including 
procedures to catalog nodes and manage root directories with 
ns__helper. 

Is a comprehensive discussion of the network environment, includ- 
ing both start-up procedures and files and server reference infor- 
mation. 

Describes registries, the /etc/passwd and /etc/group files, and 
how to update and replicate registry information. 

Discusses system and software security, the ACL system and 
Domain®/OS modes and how they interact. 

Describes the line printer system and how to configure and man- 
age it in the SysV environment. 

Describes how to configure and maintain the uucp subsystem in 
the SysV environment. 

Documents sendmail and how it operates in the SysV environ- 
ment. 

Contains the manual pages for SysV commands used for system 
administration. 

Contains manual pages for SysV special hardware peripheral and 
device drivers. 

Contains information on using netmain and netmain_srvr. 
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Intended Audience 



This manual is intended for users familiar with SysV software, the Domain/OS system, and 
the UNIX* operating system. 

The best introduction to the Domain/OS system is Getting Started With Domain/OS 
(Order No. 002348). This manual explains how to use the keyboard, display, read, and 
edit text, and manipulate files. It also shows how to request Domain/OS services using in- 
teractive commands. 

If you are not familiar with the UNIX operating system, we recommend that you read one 
of the following documents: 

© Bourne, Stephen W. The UNIX System . Reading: Addison-Wesley, 1982. 

© Kernighan, Brian W. and Rob Pike. The UNIX Programming Environment , 
Englewood Cliffs, Prentice-Hall, 1984. 

• Thomas, Rebecca and Jean Yates. A User Guide to the UNIX System . Berkeley: 
Osborne/McGraw-Hill, 1982. 



Related Manuals 

The file /install/doc/apollo/os.v./ate.tt software release number manuals lists current ti- 

tles and revisions for all available manuals. For example, at SR10.0 refer to /install/doc/ 

apollo/os.v. 10.0 manuals to check that you are using the correct version of manuals. 

You may also want to use this file to check that you have ordered all of the manuals that 
you need. 

(If you are using the Aegis™ environment, you can access the same information through 
the Help system by typing help manuals.) 

Refer to the Domain Documentation Quick Reference (Order No. 002685) and the Domain 
Documentation Master Index (Order No. 9011242) for a complete list of related docu- 
ments. 

Making the Transition to SRI0 Operating System Releases (Order No. 011435) describes 
how to make the transition from Software Release 9.7 (SR9.7) of the Domain operating 
system to Software Release 10. It includes an overview of new features and discusses the 
implications of operating a network of mixed-release (SR9.x and SR 10) machines. 

Managing Domain Routing and DomainlOS in an Internet (Order No. 005694) describes 
managing Domain/OS software in an internet environment. 



*UNIX is a registered trademark of AT & T in the USA and other countries. 
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Using Your SysV Environment (Order No. 0011020) is the first volume you should read. 

It explains how SysV works, and contains material on the Bourne shell, C shell, and Mail. 

SysV Command Reference (Order No. 005800) describes all the shell commands supported 
by SysV. 

SysV Programmer's Reference (Order No. 005801) describes all the SysV system calls and 
library functions. 

The Domain C Language Reference (Order No. 002093) describes C program development 
on the DOMAIN system. It lists the features of C, describes the C library, and gives infor- 
mation about compiling, binding, and executing C programs. 

The DomainlOS Call Reference , Volumes 1 and 2 (Order Nos. 007196, 012888) describes 
calls to operating system components that are accessible to user programs. 

Installing Software with Apollo's Release and Installation Tools (Order No. 008860) pro- 
vides instructions on installing software on your system. 

The DPSS/Mail ™ User's Guide (Order No. 003660) describes the DPSS/Mail system. 

The Domain Display Manager Command Reference (Order No. 011418) provides descrip- 
tions of all the commands used for operating the DM. 

Using TCP/IP Network Applications (Order No. 008667) provides instructions for using 
TCP/IP. 

Configuring and Managing TCP/IP (Order No. 008543) describes how to configure and 
maintain TCP/IP on your network. 

Programming with Domain/OS Calls (Order No. 005506) gives examples on how to use the 
Domain/OS calls. 

Programming with SysV STREAMS (Order No. 012275) describes how to program with 
SysV STREAMS. 

Getting Started with SysV STREAMS (Order No. 012276) provides an introduction to SysV 
STREAMS. 

Managing the NCS Location Broker (Order No. 011895) describes the NCS Location Bro- 
ker. 



Problems, Questions, and Suggestions 

We appreciate comments from the people who use our system. To make it easy for you to 
communicate with us, we provide the Apollo® Problem Reporting (APR) system for com- 
ments on hardware, software, and documentation. By using this formal channel, you make 
it easy for us to respond to your comments. 
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You can find more information on how to submit an APR from the appropriate Command 
Reference manual (Aegis, BSD, or SysV). Refer to the mkapr (make apollo problem re- 
port) shell command description. You can view the same description online by typing: 

$ man mkapr (in the SysV environment) 

% man mkapr (in the BSD environment) 

$ help mkapr (in the Aegis environment) 

Alternatively, you may use the Reader’s Response Form at the back of this manual to sub- 
mit comments about the manual. 



Documentation Conventions 

Unless otherwise noted in the text, this manual uses the following symbolic conventions. 

literal values Bold characters in formats and command descriptions represent 

commands, keywords and pathnames that you must use literally. 

user-supplied values Italic words or characters in formats and command descriptions 

represent values that you must supply. 

sample user input In examples, information that the user enters appears in color. 

output Information that the system displays appears in this 

typeface. 

Square brackets enclose optional items in formats and command 
descriptions. 

Braces enclose a list from which you must choose an item in for- 
mats and command descriptions. 

A vertical bar separates items in a list of choices. 

Angle brackets enclose the name of a key on the keyboard. 

The notation CTRL/ followed by the key name indicates a control 
character sequence. Hold down <CTRL> while you press the key. 

Horizontal ellipsis points indicate that you can repeat the preced- 
ing item one or more times. 

Vertical ellipsis points mean that irrelevant parts of a figure 
or example have been omitted. 



□□ This symbol indicates the end of a chapter. 
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This manual provides an overview of system administration in the SysV environment, as 
well as a summary of the major changes made to the system at Software Release 10 
(SR10). The manual refers to all Apollo devices that communicate on the network as 
“nodes,” although, where appropriate, we distinguish between nodes with displays and 
keyboards (for example, the DN3000 series) and nodes without (for example, the DSP160) 
since they are sometimes configured in different ways. 

Information in this manual also assumes a single Domain network; if your site operates in 
an internet, please refer to the book Managing Domain Routing and Domain/OS in an 
Internet for any additional information about system administration in that environment. 

This book deals with system software, that class of programs that manages the functioning 
of the operating system. We assume a certain level of familiarity with SysV user-level 
commands and concepts. If you’ve read and understood the Using Your SysV Environment , 
you should have no difficulties with anything explained in this book. 



1.1 System Administration Responsibilities 

As a system administrator, you are generally responsible for some or all of the following 
tasks: 

© Enabling nodes to communicate in the network by cataloging disked nodes, 
providing partners for diskless nodes, and maintaining root directories. 

© Creating processes to provide both network-wide and per-node services like 
printing, remote login, and diskless node booting. 

© Understanding how to configure and administer individual nodes within the 

network. (While individual node users will sometimes wish to determine the system 
software that runs on personal nodes, the system administrator is almost always a 
source for advice and assistance.) 

© Creating and managing a registry of authorized user and account information, 
including accounts and group and organization lists. 

© Determining access to system software, programs, and users’ files. 

© Backing up both system software and user files on a regular basis. 
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1.2 Changes to the Operating System at SR10 



We’ve made some major changes to broad areas of the operating system at this release. 
The major areas of the operating system affected, especially with regard to system 
administration, are the registry, protection (file and directory permissions), and the way in 
which the names of file system objects are represented. In the following subsections, we 
provide a brief discussion of the changes and their impact on SysV system administration. 
Complete information about these areas, as well as procedures to perform common 
administrative tasks, can be found in the appropriate chapters of this book. For 
information on conversion tools and compatibility between pre-SRIO and SR10 versions of 
these subjects, see Making the Transition to SR10 Operating System Releases. 



1.2.1 Case Sensitivity and Names 

At SR10, the operating system is completely case sensitive. We do provide conversion 
tools, however, to ease the transition from a case insensitive environment to a 
case-sensitive one. See Making the Transition to SR10 Operating System Releases. 

The most obvious effect of case sensitivity in the operating system is that the system will 
interpret mixed-case pathnames literally. For example, this means that the pathnames 
/DIRECTORY/FILENAME, /directory/filename, and /DiReCtOrY/fllEnAmE are no 
longer equivalent by default. 

If you don’t need to use mixed-case names, you can avoid many problems by setting the 
environment variable DOWNCASE to TRUE. From the point of view of naming, this will 
give you a pre-SRIO environment. However, DOWNCASE is intended as a temporary 
measure and may become obsolete at a future release. Don’t rely on this mechanism for 
the long term. 

Case sensitivity can also introduce some incompatibilities in existing shell scripts and 
programs. For a full discussion of the impact of the changes to naming at SR10 on 
programs and shell scripts, see Making the Transition to SR10 Operating System Releases. 

The Naming Server Helper (ns_helper) will continue to be case insensitive, but we 
recommend to system administrators that new node names reflect the case-sensitive world, 
both to avoid confusion and because ns_helper may become case sensitive at a future 
release. The nsjhelper is discussed in Chapter 2. 

The maximum number of characters in a leaf (single file or directory) name has been 
increased from 32 characters to 255 characters. The maximum length of a pathname that 
the system can handle has increased from 256 characters to 1023 characters. 



1.2.2 The Registry 

The registry is the mechanism that controls user access and authentication; it has 
undergone significant change at SR10. Registry information is now stored in a replicated 
database which is managed by certain components of the Apollo Network Computing 
System™ (NCS). 

A registry server and registry server database manage the overall registry function, and the 
operating system gains access to registry information via the registry server. Each node has 
a local registry available to provide node-specific registry history information so that a user 
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can log in in the event of network failure. A local cache of name-to-UID (Unique 
Identifier) mappings is maintained on each node to improve performance. 

The SR 10 registry includes the concepts of membership lists, groups, and organizations, 
which allows sites some flexibility in how the registry information is maintained. It also 
introduces the concept of ownership as a means of controlling access to registry database 
information. Simply stated, you must own a registry database relation to be able to change 
it. With these two additions, it is now an easy matter to partition a network’s registries into 
logical groupings of organizations and groups, simplifying system administration. 

The system administrator manipulates accounts by means of the edrgy tool. With edrgy, 
you can create and delete accounts, as well as edit and perform global operations on other 
registry database information. 

It is possible to run a mixed network of pre-SRIO and SR10 machines, but you’ll probably 
wish to site the SR10 registries and the pre-SRIO registries on different nodes. If your 
network is small enough that keeping two types of registries will absorb too much disk 
space or be too confusing otherwise, you should consider converting to SR10 all at once. 
Information about operating in an environment of mixed registries is available in Making 
the Transition to SR10 Operating System Releases. 

Complete information about creating and maintaining SR10 registries is available in Chapter 
4. Tools are available to convert existing registries from pre-SRIO to the SR10 format and 
to convert SR 10 registry information back to the pre-SRIO form. The intention is that, at 
some future release, all registries will be converted to the SR10 format. Descriptions of the 
various registry conversion tools and procedures can be found in Making the Transition to 
SR10 Operating System Releases. 



1.2,3 Protection: The Access Control List 

At SR10, the Access Control List (ACL) mechanism, which manages file system object 
protection, has been simplified and altered. Every object in the file system has an ACL 
that consists of four required entries for owner, group, organization, and world. Each entry 
consists of a Subject Identifier (SID) and some rights specifications. Additional protection 
entries, if required, are stored in an ‘‘extended ACL” that is essentially like the pre-SRIO 
ACL. See Chapter 5 for information about ACLs. The ACL inheritance mechanism, which 
is based on the initial file or directory ACL, survives unchanged at SR10. 

As a result of these changes, so-called “canned” ACLs, predefined sets of rights 
specifications for certain account names, are no longer supported. The changes to ACLs 
also include new versions of the acl, edacl, and salad commands to operate with the new 
and changed rights. Note that the new ACL structures will also have an impact on what 
protection information is preserved on backups. 



System Administration Overview 



1-3 




Because of the general incompatibility between the SR 10 ACL manager and the ACL 
manager prior to SR9.7, there is no way to share files between pre-SR9.7 and SR10 
nodes. If your site has few enough nodes that you can update to SR10 all at once, you 
should do that; if your site is upgrading to SR10 over a long interval, and you must be able 
to access all files on all nodes at all times, you should install SR9.7 before updating any 
nodes to SR10. For information about transition information and system software 
installation, see the books Making the Transition to SR10 Operating System Releases and 
Installing Software with Apollo's Release and Installation Tools . 

At SR10, all mapping between UNIX modes and ACLs is handled transparently, without 
any intervention by the system administrator or user. The entire UNIX protection model 
operates exactly as you would expect in a “standard” UNIX system. 
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Maintaining Nodes and 
Providing Services in the Network 



This chapter assumes that your installation consists of a single Domain network. If you 
have multiple Domain networks connected in an internet, you have other considerations. 
See Managing Domain Routing and Domain/OS in an Internet for additional information 
about how to catalog nodes and maintain root directories in an internet environment. 

Topics covered in this chapter include cataloging nodes and maintaining node root 
directories, using the ns_helper process to maintain root directories, and providing such 
network-wide services as printing and remote login. 



2.1 The Root Directory 

To communicate over the network, nodes must recognize each other. Each node has a 
root directory that associates node names and hexadecimal node IDs for all the nodes on 
your network; this ensures that communication and file access between and among nodes 
can take place. You must maintain node root directories accurately if all the nodes in your 
network are to operate efficiently. If a node's root directory is incomplete or inaccurate, 
the node may be unable to communicate with other nodes on your network. 
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This section describes 



• Node names and node IDs 

• The process of cataloging associations between nodes and node names 

• How to maintain root directories 

• An automated way of maintaining nodes’ root directories, the ns_helper (Naming 
Server Helper) process 



2.1.1 Node IDs 

Every node has a unique hexadecimal ID number (the node ID) which is contained in a 
Programmable Read-Only Memory (PROM). The only way a given node’s ID changes is if 
a service representative physically replaces the node’s ID PROM. The node ID allows both 
the network communications software and other nodes’ software to recognize that node. 

Machines are always identified by a node ID. In an internet environment, a network 
number is prefixed to the node ID to specify a nodes location. 



2,1.2 Node Names 

Since hexadecimal numbers are not easy to remember, you can associate a node name 
with a particular node ID and refer to the node by name when using shell commands like 
lvolfs (list volume free space) that allow you to specify a node with the -n option. All the 
name-ID associations that a node knows about are stored in the node’s root directory. 

A node name must begin with a letter, and all alphabetic characters in the name must be 
lowercase. You can assign node names to both disked and diskless nodes, but a diskless 
node’s name does not always act the same way as a disked node’s. In particular, you 
should remember that a diskless node’s name is not the same as its entry directory name, 
as is the case with disked nodes. For example, if the node “dublin” were disked, the 
following command would list the contents of dublin’ s entry directory. 

$ Ss //dublin 

If the node dublin were diskless, the same command would result in “object not found.” 

You associate node names with node IDs by means of the ctnode (catalog node) 
command. Later in this chapter, you'll find procedures that demonstrate how to catalog 
nodes, both in the node's own root directory and in the root directories of other nodes. 
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2.1.3 Cataloging a Node 



The ctnode command enters the node’s name, hexadecimal ID, and other information in 
the root directory. You must catalog a node whenever you 

© Add a new node to the network. 

© Change a cataloged node’s name. 

© Replace a node’s disk. 

© Run the invol utility on a node’s disk. 

® Have a node’s ID PROM replaced. The PROM installation procedures recatalog 
the node’s directories with its new ID. You then must update root directories on 
the rest of the network with the new node ID. 

A new disked node arrives at your site already cataloged in its own root directory. Its 
default name is nodejnnnnn , where nnnnn is the node’s hexadecimal ID number. Diskless 
nodes are not already cataloged. We strongly suggest that you name all the nodes in your 
network. 

Cataloging a node is a two-step process. First, you must catalog the node in its own root 
directory (or, for diskless nodes, in the partner’s root directory). Then, you must make 
this information available to all other root directories in the network. How you propagate 
the node name information to the other root directories on the network depends on 
whether your network uses the ns__helper server process to maintain root directories. 

The ns_helper maintains a master copy of the root directory and provides node-name to 
node-ID associations. It reduces the cataloging effort when you add nodes or change 
names, and is very useful in larger networks. You must run the ns_helper process if you 
have a Domain internet, and you should run it if your network configuration changes 
frequently. For complete information and procedures for using nsjhelper and the edns 
tool which accompanies it, see Section 2.3. 

If your network is small, node names seldom change, and new nodes are added to the 
network infrequently, you probably don’t need to run ns_helper. In this case, you’ll use 
the ctnode and uctnode (uncatalog node) commands and Procedures 2-1 through 2-6 in 
this chapter to maintain the root directories of nodes on your network. Many of these 
procedures will not operate in an internet. See Managing Domain Routing and Domain/OS 
in an Internet for information about using ns_helper on a Domain internet. 
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2.1.4 Cataloging a Node in its Own Root Directories 

Use Procedures 2-1 and 2-2 to catalog a disked or diskless node in its local root 
directory. The procedures catalog the diskless node in its partner node’s root directory. 

Use one of these procedures whenever you catalog a node except for when a PROM is 
changed. In this case, the PROM installation procedures recatalog the node in its own root 
directory; however, you must still recatalog the node in other nodes’ root directories if you 
do not use ns_helper. 

• Use Procedure 2-1 to catalog a node that has a display (that is, any node except 
a Domain Server Processor). 

• Use Procedure 2-2 for a a server node that does not have a display. 

• If you are cataloging more than one node, use Procedure 2-1 or 2-2 at each 
node you are cataloging. 

• These procedures only catalog a node in its local root directory. If you do not use 
ns_helper, you must continue with Procedure 2-3, 2-4, 2-5, or 2-6 to provide 
this information to all other nodes. 

Please read through each procedure before you attempt to carry it out. If you receive error 
messages when you carry out the procedures, check the command line to be certain that 
you have given the correct input. If you are sure you are giving the correct input but you 
continue to receive error messages, check with Customer Service or your designated service 
representative. 
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Procedure 2-1. Cataloging a Node in its Own Root Directory 



Task 1: 
Task 2: 

Task 3: 



Task 4: 



Task 5: 



Log in as user 

Determine the node’s hexadecimal ID 
$ lcnode -me 

The node ID of this node is 8523. 

Uncatalog the old node name 

If this is a new diskless node, you replaced the disk on an already-cataloged node, or 
you ran invol, go to Task 4. If this is a new disked node, the initial node name is the 
node ID preceded by node_, for example, node_8523. In the following example, the 
-1 option lists the node’s name after it is uncataloged. 

$ uctnode node_8523 -1 
"node_8523" uncataloged. 

Catalog the new node name 

Enter the following command if you are cataloging a new node or are giving a node a 
name that has never been used before. For example, to name the node with 
hexadecimal ID 8523 “salmo,” type the following: 

$ ctnode salmo 8523 -1 
Node 8523 cataloged as '’salmo" . 

Enter the following command if you are reusing an existing name. You usually reuse a 
name when you change disks, run invol, or replace a node and the user wishes to 
keep the old node name for the new node. 

$ ctnode oldjiame nodejd -1 -r 

Update the node’s root directory 

This step adds node name-ID associations for other nodes on the network to this 
node’s master root directory. 

$ ctnode -update -1 
3 nodes responded! 

Node 8555 cataloged as "arctic_char" 

Node 8523 cataloged as "rainbow" 

Node 8525 cataloged as "brook" 

NOTE: Perform this step only if you do no use ns_helper. 
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Procedure 2-2. Cataloging a Domain Server Processor 



Task 1: 



Task 2: 



Task 3: 



Use this procedure to catalog Domain Server Processors (DSPs) . If you're setting up a 
new network, catalog DSPs after you’ve cataloged nodes with monitors. Get the DSP's 
node ID from the inspection slip attached to the shipping carton packing slip. If you 
do not have the inspection slip, contact your service representative; this is the only 
reliable way to determine the node ID when the node is uncataloged and you don't 
have the packing slip. You must have the node ID before you start this procedure. 



Log in to the DSP as user 

Enter the following command at a shell prompt on a node with a monitor. Note the 
two single quotes (”) at the end of the command line, which show that the account 
user has a null password. For example, if the DSP’s node ID is 8533, type the 
following: 

$ crp -on 8533 -login user " 

Connected to node 8533 

Uncatalog the old node name 

If you replaced the disk on an already-cataloged node, or you ran invol, go to Task 
3. If this is a new DSP, the initial node name is the node ID preceded by node_, for 
example, node_8533. In the following example, the -1 option lists the node's name 
after it is uncataloged. 

$ uctnode node_8533 -1 
"node_8533" uncataloged. 

Catalog the new node name 

Enter the following command if you are cataloging a new DSP or are giving a DSP a 
name that has never been used before. For example, type the following to associate 
the name “chinook” with the DSP with node ID 8533. 

$ ctnode chinook 8533 -1 

Node 8533 cataloged as "chinook 11 . 

Enter the following command if you are reusing an existing name. You usually reuse a 
name when you change disks, run invol, or replace a node and the user wishes to 
keep the old node name for the new node. 

$ ctnode old name node id -1 -r 
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Task 4: Update the node’s root directory 



This step adds node name-ID associations for other nodes on the network to this 
node’s master root directory. 



$ ctnode -update -1 

3 nodes responded! 

Node 8523 cataloged as "rainbow" 
Node 8525 cataloged as "brook" 
Node 8533 cataloged as "chinook" 
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2.2 Using ctnode to Catalog Nodes on the Network 



Once you catalog a node in its own root directory, you must then provide the information 
to all other nodes’ root directories, so that remote nodes can communicate with the newly 
cataloged node and have access to its files. If the network is small and node configurations 
don’t change often, you can use the ctnode and uctnode commands to manage the 
network root directories. Procedures 2-3 through 2-6 show the steps you must follow to 
update the root directories. Use these procedures as detailed below. If you have a larger 
network, you should probably run the ns_helper process. Go to Section 2.3 for 
information and procedures for using ns_helper. 

• Use Procedure 2-3 to create a new network or to add several nodes to a network. 

• Use Procedure 2-4 to add a single node to an existing network. 

• Use Procedure 2-5 to change the name of a node that is already on the network. 

• Use Procedure 2-6 after replacing a disk drive, running invol, or if your service 

representative replaced a node’s PROM. 

All these procedures assume that you’ve already cataloged the node in its own root 
directory, using either Procedure 2-1 or 2-2. 
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Procedure 2-3. Creating a New Network 



Task 1: Log in as user 

Task 2: Update the root directory 

Enter the ctnode -update command to update the node’s root directory to include 
information on all nodes that are currently responding to network queries. In the 
following example, the -1 option lists the nodes as they are cataloged. 

$ ctnode -update -1 
2 nodes responded! 

Node 8555 cataloged as "arctic_char" 

Node 8525 cataloged as "brook" 

The local node now has a complete root directory. If the number of nodes 
responding does not equal the number of nodes in your network, repeat Task 2 until 
you get a full root directory. 

Task 3: Propagate new information across the network 

You must propagate the new name-ID information to the root directories of all other 
nodes. Enter the name of the node you’re logged into in place of //nodejiame in the 
following command line: 



$ ctnode -md -from / /node name -on //?* 




Procedure 2-4. Cataloging a New Node in an Existing Network 



Task 1: Log in as user 

Task 2: Catalog the new node 

Catalog the new node on all other nodes in the network with the following command. 
Substitute the node’s name and ID in the appropriate places. 

$ ctnode node name node ID -on //?* 
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Procedure 2-5. Changing A Node’s Name 

Task 1: Uncatalog the old name 

Repeat this task at each node on the network to uncatalog the node’s old name. 
Otherwise, the node will be cataloged under both the new and the old name. 

Log in as user. Enter the uctnode command to remove the node’s old name from the 
root directory. 

$ uctnode cutthroat -1 
"cutthroat" uncataloged. 

Task 2: If you are not still logged on, log in to any node as user 

Task 3: Update root directories 

To propagate the new node name to the root directories of all nodes in the network, 
recatalog the node under its new name. In this example, the node ID is cff. 

$ ctnode sockeye cff -r -on //?* 



Procedure 2-6. Updating Information for an Existing Node Name 

Use this procedure after replacing a disk drive, running invol, or if your service 
representative replaces a node’s PROM. 



Task 1: Log in to any node as user 

Task 2: Recatalog the node in its own root directory 

To recatalog the node in its own root directory, enter: 

$ ctnode node_name nodeJD -r 

Task 3: Update the root directories across the network 

To propagate the updated information into the root directories of all nodes in the 
network, enter the recataloged node’s name and ID in the following command: 

$ ctnode nodejxame node__ID -r -on //?* 
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2.3 The Naming Server Helper: nsjhelper 

The nsjhelper, the naming Server Helper, is a Domain server process that provides an 
automated method of maintaining node root directories. You can run nsjhelper on any 
Domain network, but you must use it on each Domain network in an internet. See 
Managing Domain Routing and DomainlOS in an Internet for information about running 
ns_helper in an internet. 

The nsjielper (/sys/ns/ns__helper) process manages a master root directory. This database 
is the only comprehensive source of node identifying information in the network. The 
nsjielper performs most of its operations automatically. The edns utility, an interactive 
tool used with nsjielper, is available for those operations requiring your intervention, such 
as updating the database. 

The nsjhelper maintains a cache of the master network root directory at each node. 
Whenever the naming server uses the master root directory to locate objects, it updates the 
local node’s cache. Although the shell command ctnode is operative, you need not 
maintain a node’s root directory with ctnode -update in the nsjielper environment. It is 
always necessary to catalog an entry directory name with ctnode when a node is first 
brought into the network. 

When more than one nsjielper runs in a network, each process is called a replica. The 
the ns_helper propagates changes in the database of any replica to all other replicas for a 
period of 14 days. In exceptional circumstances of node, loop, or disk failure, a replica 
may not receive updated information in this time period. Use an edns merge command to 
return replicated databases to a consistent state in these cases. 

We recommend running nsjielper as a background process. Enable ns_helper from a 
start-up file (usually /etc/rc) so that it will continue after logout. The nsjhelper names 
itself “nsjielper” by default, so you need not specify the -n option to the process creation 
command. 



2.3.1 The nsjielper Database 

The nsjhelper manages a database that is divided into two parts: a master root directory 
and a replica list. The master root directory is the comprehensive source of node 
identification information in the network. You can specify the node names and addresses 
in the master root directory. Only the nodes themselves can supply nsjhelper with the rest 
of the information in the directory. The ns_helper database resides in the 
‘node_data/systemJogs directory. 

On large networks and on Domain internets, you can have more than one nsjielper 
process, each with its own copy of the database; these are called replicated nsjielpers and 
databases. In this case, the database replica list includes the nodes that run nsjielper. 
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Table 2-1 lists the ns_helper database contents in detail. 



Table 2-7. Contents of the nsjielper Database 



Item 


Definition 




Master Root Directory 


Node Name 


The name of the node. 


Address 


The network number (0 for Domain single networks) 
and the node’s hexadecimal ID. 


Entry Type 


The type of object — for disked nodes, system directory 
(sdir); for diskless nodes, node (node) 


UID 


The Unique Identifier (UID) for a node’s entry directory. 
For diskless nodes, ns_helper assigns a UID. 


Entry Date and Time 


The date and time at which this entry was added to the 
master root directory. 


Creating Node 


The hexadecimal ID of the node at which the entry was 
added to the master root directory. 


Replica List 


Replica List 

The hexadecimal IDs of all nodes that run the ns_helper 
process. 



2,3.2 When to Use ns_helper in Your Network 

Use ns_helper in networks where new nodes are introduced frequently, when many nodes 
have multiple users, and when you want to maintain all the node root directories from one 
location. As we said before, you must run ns_helper on each network in an internet. 



2.3.3 Number and Placement of Replicated ns_helpers 

In smaller networks, a single ns_helper process provides a reliable way to keep nodes up 
to date. In some environments, however, you may choose to run the ns_helper server on 
several nodes. Consider running more than one ns_helper process when 
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• You have many nodes in your network, and a single server may not be able to 
handle the traffic. 

• You want to ensure that the server process is always available; two or more servers 
will provide redundancy. 

® Loops in your network are switched out regularly and/or your network runs 
through several buildings. You might want servers in each loop or building. 

You can run ns_helper only on disked nodes. 



2,3.4 Replica List 

When more than one ns_helper runs on a network, the server processes maintain 
information about each other in a part of their database called the replica list (see Table 
2-1). The replica list contains the hexadecimal ID of every node running ns_helper. You 
manage replicated ns_helpers with the edns command. 

Each ns_helper automatically tries to keep its own database (master root directory and 
replica list) consistent with those of the other ns_helpers. When you make changes to any 
database, that node’s nsjhelper refers to its replica list for the node IDs of other replicas. 
Then the ns_helper sends the new information to all the other nodes on the list. When 
ns_helpers receive new information from another server, they update their own databases 
and return an acknowledgment to the sending server. 

If the sending ns_helper does not receive an acknowledgment from all the nodes on its 
replica list, it continues to propagate the new information for a few days. In exceptional 
circumstances, a replica might never receive updated information. You can use the edns 
merge facility to return replica databases to a consistent state in these cases. 



2.3.5 Managing Root Directories with nsjhelper 

When ns_helper runs in a network, the naming server (the part of the operating system 
that locates file-system objects) has two sources of information about entry directory 
names: the node’s local root directory and the ns_Jielper master root directory itself. 

When the naming server tries to locate an object, it first looks in the node’s root directory. 
If the name isn’t there, the naming server refers to ns_helper’s master root directory for 
information about the entry name. Whenever the naming server gets information from the 
master root directory, it adds that information to the node’s root directory. 
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Using ctnode and uctnode with ns_helper 

When you use ns_helper on the network, you normally will not need to use the ctnode 
command to maintain a node’s root directory. 

There is one situation in which you’ll need to use uctnode: When you change the name 
of a node in the ns_helper database, the new name is added to the individual nodes* root 
directories, but the old name is not deleted from any of them. Use uctnode at each node 
on the network to remove the old entry from all root directories. 



NOTE: After uctnode removes an entry directory name, objects 

cataloged under that node’s entry directory are no longer 
accessible to you or other nodes on the network. 

The following subsections describes tools, considerations, and procedures for managing root 
directories on networks that use ns_helper. 



The edns Utility 

The edns (edit naming server) utility manages the ns_helper and its database. Table 2-2 
briefly describes the edns commands. The SysV Command Reference describes the edns 
commands in greater detail. Online help is also available by using the help command. 



2-14 Maintaining Nodes and Providing Services 




Table 2-2. The edns Commands 



Command 


Description 


add 


Adds a node name and the corresponding address to 
the master root directory (s). 


addrep 


Adds the address of an ns_helper node to the 
ns__helper replica lists (s). 


cmp 


Compares two ns_helper databases and lists entries 
that appear in both, or that appear inconsistently in 
both. 


delete 


Deletes the entry for the specified name from the 
ns_helper master root directory (s). 


delrep 


Deletes an ns__helper node from the nsjhelper replica 
lists. 


diff 


Lists the differences between two ns__helper databases, 
including both the master root directories and replica 
lists. 


info 


Displays address and status information for the default 
nsjhelper. 


init 


Initializes an ns_helper database with data from all 
nodes that are currently responding on the network. 


Id 


Lists master root directory information. 


lr 


Lists the addresses of all ns_helper nodes on the net- 
work; can display the nodes’ current clock dates and 
times. 


merge 


Merges all entries from one nsjhelper master root 
directory (but not replica list) into another. 


merge__all 


Performs a global merge of all nsjhelper databases, 
using the default or specified ns_helper database. 


quit 


Ends the current edns session. 


replace 


Changes the address and UID associated with the 
specified name. 


set 


Sets the default ns_helper to be the one running on 
the specified node. 


shut 


Shuts down the nsjhelper on the specified node. 
This command deletes that node’s database but does 




not remove the node from other ns_helper replica 
lists. 


update 


Updates all replica master root directories with data 
from all nodes that are currently responding on the 
local network. 
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Synchronizing Clocks on Replicated Databases 

The ns_helper processes keep only the most recent information about an entry in their 
databases. The servers use the node hardware clocks and the database item “Entry 
Date/Time” to recognize the most recent information. Therefore, you must keep the 
hardware clocks on all ns_helper nodes synchronized. Check the node clocks periodically 
and reset them if they diverge by more than a few minutes. The edns command provides a 
way to check clock synchronization (see Procedure 2-15). Procedure 2-7 explains how to 
synchronize node clocks. 



Network Availability and edns 

Two edns operations, initialize and update, are particularly sensitive to network and node 
availability because they request information from all nodes on the network. If a node fails 
to respond, it may not be cataloged in the root directory. Therefore, it is a good idea to 
initialize the first nsjhelper process at a time when network traffic is light and all nodes 
are connected to the network. 



The edns Utility and Diskless Nodes 

When edns initializes a database, it always assigns the default name 
diskless Jbnnnnnn 

to a diskless node, where nnnnnn represents the diskless node’s hexadecimal ID. The value 
is right justified and is preceded by the number of zeros required to form a six-digit 
number. For example, if the node ID is 3d3, the edns representation of that node is 

diskless_$0003d3 

The edns utility generates a Unique Identifier (UID) for a diskless node, then associates it 
with the diskless node’s name. This information about the diskless node appears in the 
master root directory and can be copied to a node’s root directory. In a single Domain 
network, the UID and other information that edns generates for the diskless node serves 
only as a place marker for information that is used in a Domain internet. 

To name a new diskless node on an existing network that runs an ns_helper process, use 
the ctnode -root command described in the next section, or use Procedure 2-10 described 
in Subsection 2.3.7. If the node was on the network when ns_helper was initialized, it 
already has a default name; in this case, use Procedure 2-12 or use uctnode -root to 
uncatalog the node before recataloging it. 
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The command Is // -In lists the names of all diskless nodes in the local copy of the root 
directory. The following commands also specify if a node is diskless: 

$ netstat -n nodejspec 
$ lusr -n nodejspec 
$ bldt -n nodejspec 
$ lcnode -me 

(The nodejspec argument can be either a hexadecimal node ID or the node entry 
directory, that is, //nodejiame.) 



2 . 3.6 User Procedures for Updating the Master Root Directory 

The ctnode and uctnode commands support a small subset of operations on the master 
root directory. Any user can run these commands to manage the master root directory 
entries. 

Use the following command to delete the entry for a node name in both the node's root 
directory and the master root directory. If you remove a node from the network, this 
command removes the old node's entry from the master root directory. If you are 
changing a node's name, use this command to remove the entry for the old name before 
adding the new name. 

$ uctnode nodejiame -root 

NOTE: Any time you change a node’s name and ns_helper is not 

running or being used, you must use uctnode on each node to 
delete the old entry from that node's root directory. 

Use the following command to add a node name in the root directory and the master root 
directory. You can use this command to give a diskless node a name or to add a new 
node to the network. 



$ ctnode nodejiame nodejd -root 

Use the following command to replace the node ID or UID that is associated with an 
existing node name in the root directory and the master root directory. You can use this 
command if your disk is changed or if you run invol. You can also use this command to 
associate an existing name to a new node. 



$ ctnode node name node id -root -r 
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2.3.7 System Administrator Procedures for nsjhelper 

The rest of this chapter contains procedures for managing ns_helper processes and 
databases. Table 2-3 lists tasks you might wish to perform and gives the number of the 
appropriate procedure. In secure networks, we recommend that you set the ACLs so that 
only the system administrator (%.sys_admin.%) can use the edns command. If you do, 
only the system administrator can perform Procedures 2-9 through 2-16 that invoke edns. 
Other users can run the ctnode and uctnode commands to manage a node’s entry in the 
master root directory as described in the preceding section. 

Table 2-3 . The nsjielper Procedures 



Description of Procedure 


Number 


Add a node to an existing network 


2-10 * 


Add node names to the ns_helper database 


2-10 * 


Add an ns_helper replica 


2-14 


Change a node’s name in the ns__helper database 


2-12 * 


Check clock synchronization on ns__helper nodes 


2-15 


Delete names from the ns_helper database 


2-11 * 


Give a diskless node a name 


2-10, 2-12 * 


Initialize a network’s ns_helper database 


2-9 


Maintain the consistency of replicated ns_helper databases 


2-16 


Reinitialize a single ns_helper process 


2-14 


Remove an ns_helper replica 


2-17 


Remove a node from the network 


2-11 * 


Unify a replica 


2-16 


Start ns_helper on one or more nodes 


2-8 


Stop an ns_helper process 


2-18 


Synchronize node clocks 


2-7 


Update ns_helper after changing a PROM or running invol 


2-13 * 



An asterisk (*) indicates a procedure that you can also perform by 
using the ctnode and uctnode commands. 
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Procedure 2-7. Synchronizing Node Hardware Clocks 



Use this procedure to synchronize node hardware clocks. You must use this procedure if 
nodes that run ns_helper are not within five minutes of each other. You should use the 
procedure if the ns__helper nodes are not within one minute of each other. 

Task 1: Obtain an accurate timepiece 

Task 2: Set the node’s NORMAL/SERVICE switch to SERVICE 



Task 3: Shut down the system 

If the node is a DSP unit without a display, you must attach either a terminal or a 
Domain node with a display to the DSP unit’s SIO (Serial Input/Output) line to set 
the node clock. Once you’ve done that, shut down the DSP. 

If the node has a display, shut it down with the DM shut command. 



Task 4: Start the calendar program 

The Mnemonic Debugger prompt (>) appears on the screen. Enter the following 
command: 

> ex calendar 

The calendar program prompts you for the required responses. (You must answer all 
questions; you cannot set the time without also entering the date.) For example, the 
following script illustrates prompts from calendar, and the responses for a node with a 
Winchester disk: 

> ex calendar 

Please enter disk type (W,S, or F)[,lvno]. 

If you do not have a disk, enter none (N) : w 

The time-zone is set to -4:00(EDT). 

Would you like to reset it? n 

The calendar date/time is 1986/07/11 13:52:03 EDT. 

Would you like to reset it? y 

Please enter today's date (year/month/day) : 1988/07/11 

Please enter the local time in 24 hr. format (hours minutes) 13:55 

The calendar has been set to 1988/07/11 13:55 EST (1986/07/11 
18:55:04 UTC) 
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NOTE: If you set a node clock backward, the node can generate 
duplicate UIDs for objects, which will create confusion in the 
operating system. You can avoid this by not rebooting until the 
amount of time you set the node clock past has elapsed. For 
example, if you set the clock back by one hour, wait one hour 
before you reboot the node. 



Task 5: Reboot the node or DSP 

Return the NORMAL/SERVICE switch to the NORMAL position and reboot. Type: 

> re 

<RETURN> 

> ex domain_os 

Task 6: Repeat Tasks 2 through 5 

Using the same timepiece, repeat Tasks 2 through 5 at each of the nodes you selected 
to run ns_helper. 



2-20 Maintaining Nodes and Providing Services 





Procedure 2-8. Starting the nsjielper Server Process 



Use this procedure to start or restart the ns__helper on any node that maintains a master 
root directory. 



Task 1: Check node clock synchronization 

If more than one node runs (or will run) ns_helpers, check to make sure that the 
nodes* clocks are within one minute of each other. To do so, enter the netstat -n 
command, followed by the node specifications of the nodes that run nsjhelpers. In 
this example, the nodes brook and golden run ns_helper. 

$ netstat -n //brook //golden 

The net_id. node_ID of this node is 0.5678. 

**** Node 4567 **** //brook 

Time 1986/07/01.15:25:57 Up since 1986/07/01.14:38:25 
Net 1/0: total- 24555 revs = 17930 xmits = 

Winchester I/O: total- 13837 reads- 11098 writes- 

No ring hardware failure report. 

System configured with 3.0 mb of memory. 

**** Node 1345 **** //golden 

Time 1986/07/01.15:21:44 Up since 1986/06/24.20:57:25 
Net I/O: total- 5572914 revs = 3892617 xmits 

1680297 

Winchester I/O: total- 244976 reads- 148445 writes- 

System configured with 2.5 mb of memory. 

If the times reported are not within one minute of each other, use Procedure 2-7 to 
synchronize the hardware clocks on the ns_helper nodes. 

Task 2: Log in 

Log in to the node that will run ns_helper. Use the appropriate procedures for nodes 
with monitors or DSPs. 

Task 3: Edit the start-up file 

Add a line to the appropriate start-up file for the node’s type; this line will start an 
ns_helper process on' this node when the node is rebooted. For DM start-up files, 
insert the following on a line by itself: 



6625 

2739 



96531 



# cps /sys/ns/ns_helper 

To start up servers via the UNIX system /etc/rc user script, uncomment the following 
lines in that script: 



# if [ -f /sys/ns/ns_helper ] ; then 

# (echo " ns_helper\c" ) /dev/console 

# /sys/ns/ns_helper & 

# fi 
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Task 4: Start the ns_helper process 

If you are working at the node you want to run ns_helper, enter the following 
command in the DM input window: 

Command: cps /sys/ns/ns_helper 

If you are working at another node (for example, if the nsjhelper node is a DSP 
server, enter the following command. You must use this command even if you are 
logged in remotely to the ns_helper node. 

$ crp -on node_spec -cps /sys/ns/ns_helper 
Where node_spec is the name of the node. 

Task 5: Verify that the server process is running 

Enter the pst command. The output from the command is shown below. 

$ ps -e 



Processor 
Time (sec) 


PRIORITY 

mn/cu/mx 


Program 

Counter 


State 


Process 

Name 


70.938 


16/16/16 


1BDE6 


Wait 


display_manager 


21.297 


1/14/16 


<active> 


Ready 


process_7 


0.850 


1/14/16 


1BD46 


Wait 


ns_helper 



Task 6: Repeat Tasks 2 through 5 

Repeat Tasks 2 through 5 at each of the nodes you selected to run ns_helper. 
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Procedure 2-9. Initializing the Network nsjielper Database 



Task 1: 



Task 2: 



Task 3: 



Task 4: 



Task 5: 



Use this procedure to initialize the ns_helper database on a new Domain network. 
We illustrate the following procedure with nsjhelper running on two nodes: golden 
(ID 8521), and brook (ID 8525) and with six nodes in the network: golden, brook, 
grayling, gila, arctic_char, and coho. 



Catalog all nodes in their own root directories 

Be sure that all nodes in the network have their own entry directory names cataloged 
in their own root directories. Procedures 2-1 and 2-2 show how to do this. 



Start ns_helper on each helper node 

Use Procedure 2-8 to start the ns_helper process on the nodes you’ve selected. 



Start edns 

Invoke edns from any node in the network with the node specification of the node 
that will run ns_helper. Our example selects brook; its ns__helper process becomes 
the default ns_helper. 

$ edns 8525 

the default ns_helper is 0.8525 
<edns> 

In the display, <edns> is the edns prompt. 



Initialize the ns_helper database 

Use the edns init command to initialize the ns_helper database that will reside on 
this node. 



<edns> init 

6 nodes responded to lcnode request 
6 entries added to directory 
0 names already existed 0 errors 



Verify that all nodes are in the database 

Enter the edns Is command to list the database and verify that it includes all nodes 
on the network. 



<edns> Is 

grayling brook golden 

gila arctic_char coho 

6 entries listed. 
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Task 6: 



Task 7: 



Task 8: 



Task 9: 



Task 10: 



Repeat Task 3 if some nodes were not added to the directory. Skip to Task 10 if you 
are only going to have one ns_helper node running on the network. 



Create an nsjhelper replica 

If you wish to run more than one ns_helper process, use the following command to 
set the default server process to a replica ns_helper node. In our example, we’re 
setting the default server to the process running on golden, so that we can create an 
ns_helper database replica on that node. 

<edns> set 8521 

The default ns_helper is 0.8521 
Initialize the replica database 

You must initialize the replica database (in the example, golden) with information 
from the original database (on brook). 

<edns> init -from 8525 

Verify that the two databases are identical 

Use the edns diff command to verify that the original and replica ns_helper 
databases contain the same information. 

<edns> diff golden brook 

The two directories are identical 

The two replica lists are identical 

If the databases are not consistent, repeat Task 7. 



Create additional replicas 

Repeat Tasks 6 through 8 for each additional replica node that you are initializing. 



Quit the edns program 

End the edns session by typing the following: 

<edns> quit 

$ 
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Procedure 2-10. Adding Nodes to the nsjielper Master Root Directory 

Use this procedure to add a node to the network and to name a diskless node if the node 
was not on the network when the ns__helper database was initialized or updated. The 
procedure updates the ns_helper master root directory with information for the new node 
and propagates the information to all replica databases. In the example, the nodes added 
to the master root directory are laker, paiute, brown, and dolly_varden. An alternate 
way to add a node to the network is via the ctnode -root command, discussed later in this 
chapter. 



Task 1: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default ns_helper is 0.8525 
<edns> 

Task 2: Add nodes to the default ns__helper root directory 

Use the following command to add each new node’s name and ID to the default 
ns_helper’s root directory: 

<edns> add node_name nodejd 
For example: 

<edns> add laker 7206 
<edns> add paiute 128c 
<edns> add brown 3333 
<edns> add dolly_varden 4b70 

Task 3: List the root directory 

Changes to the database take effect immediately. List the directory to be certain you 
did not make errors. 



<edns> Is -n 

node id name 
7206 laker 
3333 brown 
4b70 dolly__varden 
128c paiute 
503f grayling 
8525 brook 
8521 golden 
lc68 gila 
5f 6 arctic_char 

70de coho 
10 entries listed. 
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Use the edns del command to remove any errors you have made; then use the add 
command to correct information. 



Procedure 2-11. Deleting Names from the Master Root Directory 

Use this procedure to remove a node from the network or to delete any entries that you 
added incorrectly to the master root directory. In this example, the nodes laker and 
pauite are deleted from the master root directory. 



Task 1: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default nsjhelper is 0.8525 
<edns> 



Task 2: Delete entries 

Use the following command to delete the entries that you want to remove: 

<edns> del laker 
<edns> del paiute 



Task 3: List the root directory 

Changes to the database take effect immediately. List the directory to be certain you 
did not make errors. 



<edns> Is 

brown dolly_jvarden grayling 

brook golden gila 

arctic_char coho 

8 entries listed. 
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Procedure 2-12. Changing a Node’s Name 



Use this procedure if you change a node’s name, for example if you change the name of 
node 3333 from sunapee to speckled. Also use this procedure to give a diskless node a 
name if the node was on the network when the nsjhelper database was initialized or 
updated. (In this case, the diskless node already has the default name diskless J$nnnnnn, 
where nnnnnn is the node ID.) 

Task 1: Uncatalog the old node name 

Repeat this task at each node on the network. Otherwise, the node will be cataloged 
under both the new and the old name. Log in as user. Use the uctnode command to 
remove the node’s old name from the root directory. 

$ uctnode sunapee -1 
"sunapee" uncataloged. 

Task 2: If you are not logged in, log in at any node 

Task 3: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default ns_helper is 0.8525 
<edns> 

Task 4: Delete the node’s old entry from the master root directory 

Use the edns del command to delete the node’s old entry from the database. 

<edns> del sunapee 
<edns> del diskless_$009a7d 

Task 5: Add new entries 

Use the add command to create a new entry in the database with the node’s new 
name. 

<edns> add speckled 3333 
<edns> add nodisk 9a7d 
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Procedure 2-13. Replacing Information for a Node in the Master Root Directory 

Use this procedure whenever you replace a node’s disk with another disk and whenever 
you use the invol utility. These operations replace the node’s ID, and you must put the 
new information in the database. 



Task 1: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default ns_helper is 0.8525 
<edns> 

Task 2: Replace the old information 

Use the following command to replace the node ID information for the node named 
“coho.” 

<edns> rep coho 70de 
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Procedure 2-14. Adding or Initializing an nsjielper Replica 

Use this procedure when you add an ns_helper replica. Use Tasks 2 through 4 to 
reinitialize the database of an existing ns_helper replica. This procedure’s examples, 
initialize the new ns_helper replica on node coho, node ID 70de, from brook, node ID 
8525. 



Task 1: Start nsjhelper on the new node. 

Use Procedure 2-8 to start nsjhelper on coho. 

Task 2: Invoke ns_helper and set the new default 

At any node, enter the following command to invoke edns and set the default 
ns_helper directory to the new replica node, coho. 

$ edns 70de 

The default ns_helper is 0.70de 

Task 3: Initialize the replica database 

Use the following edns command to initialize the replica database from the existing 
ns_helper replica at the node brook: 

<edns> init -from 8525 

Task 4: Verify master root directories 

Use the following edns command to verify that the master root directory and replica 
list are the same on both the original replica node and the new replica node. 

<edns> diff coho brook 

The two directories are identical 

The two replica lists are identical 

If the databases are not consistent, repeat Task 3. 
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Procedure 2-15. Checking Replica Node Clocks 



Keep the clocks on ns_helper nodes synchronized because the ns_helper applies time 
stamps to the information in its database. Skewed clocks can result in new data from an 
ns_helper node with a slow clock being deleted and replaced by older (and inaccurate) 
data from a replica node with a fast clock. We recommend that you keep replica node 
clocks within one minute. The ns_helper allows more than one minute of divergence and 
will indicate the skew after the range exceeds five minutes. 

Check the replica nodes’ clocks daily until you know how long it takes for the clocks to 
diverge. You can then adjust the replica nodes’ clock inspection schedule accordingly. To 
check the nsjhelper node clocks, perform the following tasks: 



Task 1: Invoke edns 

From any node, enter the edns command: 



$ edns 

The default ns__helper is 0.8525 
<edns> 



Task 2: List replicas’ clock times 

Enter the following edns command: 

<edns> lr -clocks 

The following message from lr verifies that the replica nodes’ clocks are synchronized 
well enough for ns_helper to operate properly: 



replica 
0 . 0070de 
0.008525 
0.008521 



datetime 

86/08/09.16:52 

86/08/09.16:53 

86/08/09.16:54 



All clocks are synchronized to within ns_helper threshold. 



The next message indicates that clocks are skewed: 



replica 
0 . 0070de 
0.008525 
0.008521 



datetime 

86/08/09.16:51 

86/08/09.16:58 

86/08/09.17:03 



clock skewed 
clock skew warning 
clock skewed 



Task 3: Synchronize skewed clocks 

For skewed clocks, use Procedure 2-7 to synchronize them. Then use Procedure 2-16 
to check the inconsistencies and, if necessary, make them consistent. 
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Procedure 2-16. Maintaining Consistency of Replicated Databases 



The examples in this procedure compare and unify the databases on the “golden” and 
“brook” nodes. 



Task 1: Compare Replica Databases 

Use the edns diff command to check whether two replica databases are the same. 

This command shows any discrepancies in names, UIDs, or addresses. For example, it 
reports any discrepancies that might have been caused by skewed clocks. It also 
reports any differences in the replica lists. 



<edns> diff golden brook 



value in 
0.008521 



value in 
0.008525 



diff directory directory 

name name found name not found 

uid 21089D87 . 4000503f 2108af 41 . 4000503f 

The two replica lists are identical 



name 

gila 

grayling 



In this example, diff shows that gila is cataloged in golden’s master root directory but 
not in brook’s. It also shows that grayling has a different UID value in the two 
replica master root directories. 



Repeat the diff command until you have compared all replica nodes. For example, if 
ns_helper runs on golden, brook, and coho, the following two commands compare 
all replicas: 



<edns> diff golden brook 
<edns> diff golden coho 



Task 2: Unify Replica Databases 

The edns utility provides two commands for making replica databases consistent: 
merge and merge_all. 

The edns merge command updates one replica database from a second database. It 
operates on both the directory and replica list of an ns__helper. In the following 
example, merge adds to brook’s database any information that is present in golden’s 
database but absent from brook’s. It also replaces any information in brook’s 
database that is older than information about the same entry in golden’s database. It 
is important to note that nothing is changed in the -from replica (for example, 
golden’s) database. Type 

<edns> merge brook -from golden 



Maintaining Nodes and Providing Services 2-31 




Since merge only operates on the target replica database, it is often appropriate to 
merge all replicas into a consistent state. The edns merge_all command merges all 
replica databases, using either the default replica node or a specified node as the 
source node. 

The command merges the information from all ns_helper replicas on the source 
node’s replica list into the source node’s database, using the most recent information 
whenever there are conflicts. It then updates all other replica databases with the 
contents of the source node’s database. However, it can only get information from 
and update ns_helpers that are on its replica list. Therefore, check to make sure that 
the source node’s replica list includes all replica nodes before using merge_all. The 
following procedure uses merge_all to ensure that all databases are consistent. 

1. Invoke the edns utility. 

$ edns 

The default ns_helper is 0.8521 

2. Enter the lr command to list names of the nodes in the default ns_helper’s replica 
list. 

<edns> lr 
replica 
0.008525 
0.008521 

3. If any ns_helper replica nodes are missing from the list, use the addrep command 
to add the node. For example, the replica list in Task 2 is missing coho (node ID 

7 Ode). Enter the following command to add the node: 

<edns> addrep coho 

4. To merge all replica databases, enter 

<edns> merge_all 

In this case, the default replica node (golden) is the source node, and this command 
merges the information from brook and coho into golden. It then merges golden into 
brook and coho. 
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Procedure 2-17. Removing an ns_helper Replica 

Use this procedure to stop an existing ns_helper replica process, delete the node’s 
replica database, and delete the node’s name from all other ns_helper nodes’ replica 
lists. 



Task 1: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default ns_helper is 0.8525 
<edns> 

Task 2: Delete the replica 

Use the edns delrep command to delete the replica. 

<edns> delrep coho 

The delrep command deletes the specified node’s ID from the replica list of all other 
ns_helpers. It also causes the ns_helper at the specified node to delete its database 
and stop active service to the network. The inactive replica does not accept new 
transactions and will only accept edns info requests. It continues to run until it has 
completed sending any information it has that has not yet been propagated to the 
other replica nodes. When all information has been sent, it stops running. 

Task 3: Check for running server 

Use the pst command to see if the server process is still running from time to time. If 
you are at the replica node, enter 

$ ps -en l/nodejiame 

If you are at any other node, enter 

$ ps -en replica_node_specification 

If ns_helper is not mentioned in the process list, it has stopped running. 

If the deleted ns_helper is still running after a few days, you may have to stop it 
manually. This is the case if the deleted ns_helper has stopped, but the node is 
rebooted before you do Task 4; the stopped ns__helper restarts when the node 
reboots. Use the edns info command to see if the ns_helper can now be stopped. 
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$ edns 70de 

The default ns_helper is 0.70de 
<edns> info 

The default ns_helper is 0.70de 
Its status is uninitialized. 

If the info command reports that the deleted replica ns_helper is uninitialized, then it 
is appropriate to stop it. 



<edns> shut 7Gde 



Task 4: Disable ns_helper startup 

When the process has stopped, remove the following line from the appropriate 
start-up file on node 70de (coho). 

# cps /sys/ns/ns_helper 

This prevents the ns_helper process from restarting on coho the next time the node is 
rebooted. 



Procedure 2-18. Shutting Down an nsjielper Replica 

Use this procedure to immediately shut down an ns__helper and delete its database, without 
deleting the replica node ID from other ns_helper’s replica lists. Any information that the 
ns_helper has not yet sent to other replicas will not be sent and the information may be 
lost. Therefore, you should use Procedure 2-16 before you delete this replica. 



Task 1: Invoke edns 

From any node, enter the edns command. 

$ edns 

The default nsjhelper is 0.8525 
<edns> 

Task 2: Shut down the replica 

<edns> shut coho 
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2.4 Remote Process Creation: The Server Process Manager 



The Server Process Manager, spm (/sys/spm/spm), allows you to create a process on a 
node from another, remote node. On a DSP, spm starts when the operating system is 
loaded, and so it runs whenever the DSP is online. The spm also starts the mbx_helper 
program. Since they have no monitors or keyboards, DSPs would be unusable without both 
of these server processes. Once spm is started, you can create processes from a remote 
node by using the shell command crp, as well as log in to the node for debugging purposes 
or to maintain servers. 



2.4.1 Starting and Stopping spm 

To start spm from the DM command line, enter the following: 

Command: cps /sys/spm/spm -n server_process_manager 

The -n server jprocessjnanager is optional because spm names itself this when it starts. 
The process begins immediately and continues after logout. 

To invoke it from the /etc/rc file for DM start-up files, uncomment the following line in 
the file: 



# cps /sys/spm/spm -n server_process_manager 

To invoke it from the UNIX system start-up files, uncomment the following lines in that 
script: 



# if [ -f /sys/spm/spm ] ; then 

# (echo " server_process_manager\c" ) /dev/console 

# /sys/spm/spm & 

# fi 

The spm begins when the node is booted, and it continues under normal conditions until it 
is intentionally stopped with the shell command, sigp, as shown below: 



$ sigp server_process_manager -q 
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2.4.2 The shutspm Command 



In addition to the sigp command, you can also use the shutspm command to shut down 
the Server Process Manager on a remote server node. Unlike sigp, which shuts down 
only the spm process, shutspm shuts down the spm and then performs an orderly 
shutdown of the node. When you reboot the node after a shutspm shutdown, it reboots 
without performing a salvol. (If you require a salvol, shutdown the node by pressing its 
RESET button.) 

To shut down the spm with shutspm, create a remote process (via the crp command) on 
the target node and enter the shutspm command. 

To prevent spm from responding to the shutspm command, add the following line to the 
‘node_data/startup.spm file on the node or the DSP: 

no_shutspm 



The spmshut_ec File 

The shutspm command performs the shtudown by advancing an eventcount file, 
‘node_data/spmshut_ec, to the point that executes an orderly node shutdown. 

Spm creates the spmshut_ec file in the ‘node_data directory. If the default ACL for files 
created in this directory is %.%.%, spm will apply the following protection to the 
spmshut_ec file: 

Subject ID Access Rights 

%. sys_admin.% pwrx 

%.%.% r 

This ACL limits shutspm shutdown to sys_admin log-in accounts, but permits any account 
to delete the spmshut_ec file whenever spm is not using it. If the default ACL for 
‘node_data has been changed, spm creates the eventcount file with that default ACL. 

If the spmshut_ec file already exists when spm starts up, spm does not change its ACL. 
This ACL application procedure provides some control over who may shut down a remote 
server while still allowing you to administer your system the way you choose. 



2.5 Installing, Configuring, and Managing STREAMS Software 

STREAMS is Apollo’s implementation of UNIX System V Release 3 streams. STREAMS 
allows you to process “modules” into the data stream between the stream and a device 
driver after the driver is opened. This capability is particularly useful for implementing 
modular communications protocols. 
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Devices that are implemented with STREAMS drivers reside in the /dev directory as do 
other UNIX drivers, and may be accessed from any environment. Programs that access 
STREAMS devices or modules can be run from any environment. 

STREAMS modules reside in the directory /sys/streams/modules. All objects in this 
directory are loaded into global virtual memory at boot time; to prevent this, and make 
more global memory available for other software, remove modules from the directory. 

In most cases, the developer of a given driver or module will take care of compiling, 
loading and configuring it so that it is accessible. If a third party supplies a driver or 
module, installation and configuration information should accompany the software. For 
this reason, we provide installation and configuration information only in the Programming 
with SysV STREAMS manual; look there if you need specific instructions. 

You must run the STREAMS daemon, streamd, to enable access to STREAMS devices 
and modules. Typically, streamd is run from the file /etc/rc at boot time. 

STREAMS error logging commands strace, strerr, and strclean can be useful in tracking 
down problems with modules and drivers. 

See Getting Started with SysV STREAMS for more information on streamd, strace, strerr, 
and strclean. 



2.6 SysV Mail Services 

SysV users can use Domain Professional Support Services (DPSS™) as their mail delivery 
system. This subsection briefly describes DPSS/Mail™. For more detailed information on 
using and administering DPSS/Mail, see the DPSS Mail User's Guide. 

DPSS/Mail uses a subscriber directory to identify mail addresses. This directory is a field 
associated with each user's entry in the registry. You must ensure that the directory 
contains each mail user’s mail address (using the edsd command). DPSS/Mail can be 
used to send mail to UNIX systems, sendmail, and Alis* systems. 



2.6.1 DPSS Mail and UNIX Mail 

A UNIX mail gateway, supplied with DPSS/Mail, can be accessed by sending mail to 
addresses of the form user@unix (for DPSS/Mail to UNIX mail) and user@dpss (for UNIX 
mail to DPSS/Mail). These addresses must be in the subscriber directory. In addition, the 
sendmail configuration file must be changed to identify the mailer for DPSS/Mail and 
UNIX mail gateways. 



*Alis is a trademark of Applix, Inc. 
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2,6.2 DPSS/Mail and sendmail 



An optional feature allows all DPSS/Mail to be delivered through sendmail. This option 
can be configured on a system-wide basis by setting the sm option in mail/$config/ver.l7. 
See Chapter 8 for more information on sendmail. 



2.6.3 DPSS/Mail and Alis 

If you are using the Alis gateway you must install sendmail, since mail from DPSS/Mail to 
Alis is delivered via sendmail. 

There are two types of configurations for mail that enters the Alis mail system: the user 
and the gateway configurations. 

Users communicate with the gateway that allows communication with Alis, using 
sendmail _post. This configuration requires a line, similar to the following, in sendmail. cf 
to target the gateway node: 



Malis, P=/usr/lib/mailer/sendmail_post , F=lFDhum , S=10, R=20, 

A=sendmail_post $u -n //alis_gateway_node 

In the gateway configuration, sendmail_deliver executes on the node running Alis, which 
serves as the gateway. The sendmail_deliver program waits for messages and then 
executes the local sendmail. The gateway executes the Alis import program. 

The sendmail. cf on the gateway node for Alis mail looks similar to the one below: 



Malis, P=/usr/lib/mailer/alis_import , F=lFDhum , S=10, R=20, 

A=alis_import $u 

You must start sendmail_deliver via the appropriate start-up file on the gateway node. 
For example, the simplest way to start sendmail_deliver is to include the following line in 
the /etc/rc file: 

cps /usr/lib/mailer/sendmail_deliver 



88 
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This chapter describes how to administer nodes in the network environment. It includes 
information about these topics: 

© The directory structure of the network and individual nodes 
o Information on providing network services to node users 
o Information on user log in accounting 

o Node activity when the node starts up (boot time) and when a user logs in, and 
how to use start-up and log-in files 

© Steps to troubleshoot node software behavior 

© Reference information on servers used by nodes 

o Information on user log-in accounting 



3.1 The Network Directory Structure 

The operating system expects information about nodes to be organized in a hierarchy 
called the naming tree. The two naming tree components, directories and files, combine 
to form pathnames. Directory names and file names must have fewer than 255 characters; 
pathnames must have fewer than 1023 characters. Figure 3-1 illustrates the network nam- 
ing tree, including some of the standard software directories. 
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3.2 Node Directory Structure 

A node’s directory structure comprises entry and root directories, upper level directories, 
and volume entry directories. This section discusses these directory types, distinguishes be- 
tween physical and logical volumes, and explains two special characters in the file system: 
the ‘ (tick) in ‘node_data and the / (slash) identifier in the context of the directory struc- 
ture. 

Every logical volume consists on an entry directory (originally constructed by invol) along 
with any other subdirectories beneath it. For disked nodes, the entry directory of the boot 
volume becomes the node’s entry directory, that is, the node’s / directory. A nodes name, 
which ctnode specifies, resolves to the node’s entry directory, for example, //foobar. 

Other disks or volumes can be made accessible by being mounted beneath this point. 
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3.2.1 Node Entry Directories and Root Directories 



The node entry directory is the highest-level directory in a node’s naming tree that can 
contain files, links, and other directories. The entry directory name is the same as the 
disked node’s name. 

The set of node entry directory names in your network is the network root directory, 
sometimes referred to as the top-level directory. Every disked node has its own copy of 
the root directory that the operating system uses to find objects stored on other nodes. 

3.2.2 Upper-Level Directories 

Upper-level directories are one level below the node entry directory in the SysV naming 
tree structure. Upper-level directories contain system software, system and programming 
libraries, and users’ home directories. The system software installation procedures create 
the upper-level directories that the system needs to operate. In addition, you can use the 
mkdir command to establish upper-level directories on each node, such as home directo- 
ries for different users. 

You should restrict access to upper-level directories that contain system software by setting 
permissions on them so that they cannot be accidentally deleted or altered by users. Indi- 
vidual users may also want to protect all or part of their home directories by using permis- 
sions. Chapter 5 discusses protection. 

3.2.3 Disk Volumes and Volume Entry Directories 

Disked nodes have one or more physical volumes, that is, physical media. One disk drive 
is treated as a single physical volume; therefore, a node can have as many physical vol- 
umes as it has disk drive units. Each physical volume can be divided into logical volumes, 
independent partitions of the physical volume. You use the invol utility to create and 
maintain logical volumes on the physical media. 

Most nodes have one logical volume per physical volume, because this is usually the most 
efficient way to use disk space. However, you might want to partition a physical volume 
into two or more logical volumes if you want to reserve part of a large disk for temporary 
files, or if you want to have another version of the operating system on the disk, or if you 
want to be able to run salvol on only part of the disk (so that salvol will run more 
quickly) . 



Logical Volumes on SysV Systems 

SysV uses block special files (in the /dev directory) to define the logical volumes. The 
SysV installation procedure automatically creates three sets of block special files, one each 
for a single Winchester, floppy, and storage module logical volume. You must use the 
/etc/mknod command to create additional block special files for new logical volumes. 
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For example, if you install a second storage module drive on a file server node and use 
invol to partition the new disk into two logical volumes, you should create the following 
block special files: 

/dev/dsk/FOdOsl Block special file for floppy drives 
/dev/dsk/WOdOsl Block special file for Winchester drives 
/dev/dsk/SOdOsl Raw block special file for storage drives 

You use the block special files in the mount and amount commands to mount and un- 
mount the volumes. A volume must be mounted to be accessible. Any volume that you 
mount by using the mtvol command is also accessible to SysV, even if the volume does 
not have a descriptor file. The volume will also be listed in the /etc/m tab mounted volume 
table. When a node is booted from disk, the boot volume is automatically mounted and 
entered into the /etc/mtab file. 

Each logical volume that is mounted on a node has a volume entry directory. This direc- 
tory is the logical volume’s highest level directory. The boot volume’s volume entry direc- 
tory is also the node entry directory. A volume’s entry directory must be mounted on the 
next higher directory in the naming structure. The boot volume (node) entry directory is 
mounted on the root directory, the highest level directory in the network naming structure. 
The mount command automatically mounts a volume’s entry directory on its next higher 
directory when you mount the volume. 

Because the name of a directory is mounted on the next higher level directory, you can 
change the name of a volume entry directory each time you mount the volume. This is 
particularly useful when you are mounting floppy disks, because you might want to put 
floppy disks with different software at different locations in the naming tree. Thus, you 
might mount a floppy disk with data from an analysis of the performance of widgeta as 
/tests/data/widgeta. When you are done using this disk, you could unmount it and mount 
a disk with financial analysis results as /finances/q286. 



Mounting a Volume on a Diskless Node 

You can mount a logical volume on a node that you boot diskless— if the volume is physi- 
cally located at the node. This capability is useful if a node’s copy of the system software is 
corrupted and the node will not boot normally, but you must access data files on the 
node’s local disk. To mount a disk on a diskless node: 

1. Boot the node as a diskless node. 

2. Use the mknod command to make a block special file in the partner node’s 
‘node_data/dev/dsk directory for each logical volume to be mounted (if the files 
do not already exist). 

3. Use the mkdir(l) command to create a normal directory that will be mounted on 
top of the volume entry directory. 

4. Use the mount command to mount the required logical volume. 
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You must perform step 2 because a diskless node’s *node_data directory does not auto- 
matically have SysV block special files. For more information on the requirements for 
diskless nodes, see “Administering Diskless Nodes,” in Section 3.10. 

It can be useful to mount a diskless node’s boot volume in the root directory as we have 
done in this example. This way, you and others can refer to the volume’s files by using the 
usual absolute pathnames, such as //apple/helena/com/test. pas. However, mounting a 
“diskless” node’s boot volume in the root directory has no effect on the meaning of / 

(see the next section). This character still refers to the node entry directory of the partner 
node, orchard, and not to the //apple entry directory. 

In general, we do not recommend that you mount disks in the // directory. Instead, 
mount them below the / directory of the node that you have booted from. 

3.2.4 The ‘node_data and / Identifiers 

Using Your SysV Environment describes directories and links in detail. However, because 
the meaning of *node_data (tick-node_data) and / (slash) are especially important in the 
context of system administration, we go over the information here as well. 

The meanings of the identifiers ‘node_data and / (alone or at the beginning of a path- 
name) are variable, and depend on the context in which you use them. Using them incor- 
rectly, especially in links, can result in circular or otherwise incorrect references. 

As the first character of a pathname, the slash character (/) always refers to the root di- 
rectory of the node where the process is executing. Similarly, *node_data always refers to 
the /sys/node_data[.notfe_/rf] directory for the node where the process is executing. 

The / and *node_data conventions are powerful tools. The *node_data convention allows 
you to specify the node_data directory of the node you are working on, and that node 
only, even if the node is diskless. Similarly, the slash character refers to your working 
node’s entry directory, independent of the current working directory. 

Note that in UNIX shells, the 4 is a special character and must, therefore, be preceded 
with a backslash (\) . This means, for example, that you must enter the following com- 
mand to change your working directory to ‘node_data/etc in a UNIX shell: 

$ cd Vnode_data/etc 

Some examples of using / and ‘node_data follow. 



The ‘node_data Directory and Diskless Nodes 

The actual pathname of the ‘node_data directory for a diskless node is distinguished from 
its disked partner’s ‘node_data with a suffix that consists of its hexadecimal node ID. 

When you’re working on a diskless node and specify ‘node_data, the operating system un- 
derstands that to mean the /sys/node_data.node_Jaf directory on the disked partner. 

Suppose there are three nodes: brook, blue, and rainbow, as shown in Figure 3-2. 

Brook is the disked partner node for the two diskless nodes blue and rainbow. A program 
or person working at node brook who reads the file ‘node_data/startup.l91 will read the 
file //brook/sys/node_data/startup.!91. A program or person working at node rainbow 
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(node ID e467) who reads the file ‘node_data/startup. 191 will read the file 
//brook/sys/node_data.e467/startup.l91. A program or person working at node blue 
(node ID 632b) who reads the file ‘node_data/startup.l91 will read 

//brook/sys/node_data.632b/startup.l91. (Remember, however, that a program or person 
working at node rainbow or node blue who reads file /sys/node_data/startup.l91 will 
read that file on the brook node.) 



^ - b ro ok 



ns§> //brook/sys/node_data/startup. 1 91 



rainbow 

0467 



//brook/sys/node_data. ©467/startup. 1 91 



III 

1!!! 



//brook/sys/node_data.632b/startup.19l 



Figure 3-2. Reading ‘nodejdata from Diskless Nodes 



The crp Command 

When you use crp to execute commands or programs on another node, 4 node_data and / 
refer to the node_data and entry directories of that remote node. For example, if you are 
working at the node here_node and use crp to create a remote process on the node 
there_node, the following command displays the directory listing for //there_node/sys, the 
remote node’s /sys directory. 

$ Is /sys 



Circular And Unexpected References 

Because ‘node_data and / have meanings that depend upon the location of the process 
that makes the reference, it is possible to use pathnames that result in circular references 
This is particularly true when you use links to either the / or ‘node_data directory. For 
example, each node’s /tmp directory is a link to ‘node_data/tmp. If you are working at 
node bar, you might try to use the following command to list node foo’s /tmp directory. 

$ Is //foo/tmp 
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However, this command will actually list the contents of //bar/sys/node_data/tmp because 
//foo/tmp is a link to *node_data/tmp, and ‘node_data always refers to the node__data 
directory of the node executing the command, in this case node bar. Therefore, to list the 
contents of the /tmp directory of node foo when you are working at node bar, you must 
use the absolute pathname of the file in the command. 

$ Is //foo/sys/node__data/tmp 

3.2.5 The Variant Link 

Each node’s /bin, /usr, and /etc directories are links to ($systype)l bin, ($systype)/ usr, and 
($systype)/et c, where $systype is the value of the SYSTYPE environment variable. There- 
fore, if a process’ SYSTYPE is sys5.3, the process executes commands in the /sys5. 3/bin, 
/sys5.3/usr, and /sys5. 3/etc directories. 

This use of variant links allows different processes to use different versions of Domain si- 
multaneously, and ensures that each process uses the correct versions of each command 
and call. 



Symbolic Links 

The SysV ln(l) command and the Aegis crl command create symbolic links that are iden- 
tical objects and that are treated in the same way by SysV and Aegis commands. For ex- 
ample, you can delete a link created with either command with the rm(l) or the dll com- 
mand. Both In and crl create a link entry in the directory; the In -s command does not 
create a new file that contains the linkage information. 



3.3 Node Software Structure 

Figure 3-3 shows a typical node’s software structure, including system software and user 
entry directories, starting at the node entry directory level. This figure shows only the gen- 
eral way the software is organized; it does not include all software. 
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Figure 3-4 illustrates that /etc is shared at SR10. Conflicts, like /etc/cron, are resolved 
with a varient link so that the correct version of a file is processed. 
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Figure 3-4. Sample /etc Shared Directory Structure 



The exact structure of your directories and their contents will differ depending on the ex- 
act configuration of your system. Conflicts like /etc/cron are resolved with a variant link 
so that Ssystype guarantees that the correct version of the command is run 

In the figure, the node entry directory contains the SysV system software and other 
subdirectories that themselves contain SysV system software. The /sys directory contains 
system software and many of the directories used for node and network management. 

Two subdirectories of the /sys directory, the Display Manager directory / sys/dm and the 
network management directory /sys/net, *' contain files and programs you use to create and 
administer network services. All installations will have the ‘node_data directory. 

3.3,1 The ‘node_data Directory 

Every node, disked or diskless, has a ‘node_data directory. This directory contains files 
that the node needs to perform many system functions. These files include start-up and 
configuration files, per-node system files, interprocess communications mailboxes, and de- 
vice files. 

The actual pathname of a disked node’s ‘node_data directory is 
//nodename/sys/nodejlata 

The pathname of a diskless node’s ‘node_data directory is 
//partner jiode/sys/nodejdata.nodeJd 
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The optional .nodejd part of the file name enables a disked node to be a partner to one 
or more diskless nodes. 

For example, if the disked node golden is the partner node for diskless nodes sunapee 
(node ID efd3) and char (node ID f2a4), golden would have the following three directo- 
ries, each containing system operation information for its respective node. 

/sys/node__data (for golden) 

/sys/node_data.efd3 (for sunapee) 

/sys/node_data.f2a4 (for char) 

NOTE: In later examples, when we refer to a node’s /sys/node_data direc- 
tory, we use the syntax /sys/node_data[.node_id] when we want to 
show that we are talking about the /sys/node_data directory for both 
disked and diskless nodes. 

See “Administering Diskless Nodes,” Section 3.10, for further infor- 
mation about managing the /sys/node_data [.nodejd] directory for 
diskless nodes. 

3,3.2 Directories for Temporary Files and Log Files 

Apollo provides two directories for temporary files, *node_data/systmp and 
‘node_data/tmp, and one for log files, ‘node_data/system_logs. 

The ‘node_data/systmp directory is used for temporary operational files created by Apollo 
software (system and other). The ‘node_data/tmp directory (a link from /tmp) directory 
is used for temporary files created by the UNIX operating system. Files in both of these 
directories are deleted by the /etc/rc file when the system starts up. 

The ‘node_data/system_Jogs directory is used by Apollo software (system and other) to 
store log files. 

You should ensure that the files in all of these directories are writable by all users. In 
addition, you should ensure that the ‘node_data/system_logs directory is purged occasion- 
ally of unnecessary files so that it stays a reasonable size. 

By separating temporary directories from the other directories and files in *node__data, you 
can set protection for temporary files so that users can access them, but still maintain the 
overall tighter protection established for the ‘node_data directory. 



3-10 Administering Nodes in the Network 




3.4 The DM and Context Inheritance 



Whenever you execute a Display Manager command, the DM inherits its context from the 
last active display window. This context includes all environment variables, including the 
SYSTYPE value. It also includes the current working directory. This context inheritance 
has several importance effects, as follows: 

© The DM does not necessarily inherit the context from the window that currently 
has the cursor, if you have just moved the cursor into the window. You must initi- 
ate some activity in the window (if only by pressing the space bar when the cursor 
is in an input pad) before the DM can recognize the window as “current.” 

• The DM inherits the context from the window that most recently sent it input. 
Therefore, if you start some command (say an Is -1 of a long directory) in a BSD 
C shell, move to a SysV Bourne shell and execute another command (say the 
pwd command) and then move to the DM input window, a DM env SYSTYPE 
command will return the value sys5.3, even if the C shell has not completed the 
directory listing. 

• Any process that you create by executing a DM cp, cpo, or cps command inherits 
its environment variables from the DM, and therefore from the current DM con- 
text. 

© Because the DM context includes the working directory, the meaning of a relative 
pathname (for example, in a cv or ce command) depends upon the working di- 
rectory of the most recently active window. 



3.5 Using Nodes to Distribute System Resources 

When you administer a Domain network, you manage system-wide file resources, such as 
databases and libraries, and manage processes that provide network-wide services (server 
processes) . 

3.5.1 Managing System Resources 

You must manage system resources in order to distribute network resources such as data- 
bases, organize and protect user home directories, and organize and protect libraries of 
application software. 

Frequently you manage system resources by creating and managing upper-level directories. 
The decisions you make about the locations of upper-level directories that contain network 
resources will affect the performance of your network. For example, some system libraries 
and databases are large or heavily used; you should position such resources strategically to 
maintain an even flow of network traffic and optimize disk space. 
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Using Upper-Level Directories 

By assigning each library of application software its own upper-level directory, you can eas- 
ily protect the software from accidental or unauthorized changes. You can set the permis- 
sions for the libraries so that only system administrators have full rights to change contents. 
For users who only run application programs, you can set their home directories to the 
proper application program library. 

A home directory is an upper-level default working and naming directory set by the oper- 
ating system when the user logs in. Use the registry entries, as described in Chapter 4, to 
specify a user’s upper-level directory as a home directory. Refer to Using Your SysV Envi- 
ronment for a more detailed discussion of home directories. 



Creating Upper-Level Directories 

You can create an upper-level directory for each user, which can become the user’s home 
directory. A home directory is a default working and naming directory set by the operat- 
ing system when the user logs in. Users* upper-level directories do not become their home 
directories until you specify that fact in registry entries, as described in Chapter 4. Refer to 
Using Your SysV Environment for a more detailed discussion of naming directories. 

You create upper-level directories in the same manner as you create other directories, by 
entering the mkdir(l) command and specifying the directory pathname. For example, to 
create the upper-level directory joe on the node //joesjnode, enter 

$ mkdir //joes_node/joe 

You can then use chown(l), and chmod(l) to set the ownership and permissions as re- 
quired for the directory. 

3.5.2 Providing System Services 

Server processes provide services to some or all of the nodes on a network. Servers nor- 
mally run regardless of log-in and log-out activity. Server processes manage requests from 
clients, which may be programs or other processes. Clients request access to network re- 
sources Such as data, peripheral devices, or communication pathways outside the network. 



Server Processes and DSPs 

Server processes often run on Domain Server Processors (DSPs), server nodes that do not 
have displays and that are dedicated to running these processes. However, you can config- 
ure network server processes on any kind of node. 

Numbers and Locations of Servers 

The number of server process that you choose to implement depends on the particular re- 
quirements of your site. You should run server processes that manage network databases, 
ns_helper for example, on several nodes to ensure user access. For example, an 
ns_helper process must run on each Domain network that is connected to make a Domain 
internet. You might also want to run ns_helper on network loops that are frequently sepa- 
rated from a main network. 
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Decisions about the number of instantiations across the network of a particular server are 
closely related to the placement of server nodes within the network topology. For example, 
five printers can be managed from one, two, or five server nodes, depending on the loca- 
tions of the printers. If your network covers a one-story building and a larger two-story 
building, you might want three server node locations, one in the small building and two in 
the larger building. 

The location of servers affects your ability to provide services to nodes and loops as they 
are switched in and out of the network. Note that a node selected to run a network server 
process can be used for other activities. It is not necessary, and usually not desirable, to 
place all network services on one or two nodes. Servers should run on nodes that are sta- 
ble and secure. (You would not normally run ns_helper on a node in an open computing 
room or a system development node.) Become familiar with the principles of network man- 
agement and troubleshooting before you determine the numbers and locations of servers. 

3.5.3 Server Process Information 

Server processes manage requests for data access and data transfer, gather network statis- 
tics, manage access to network resources such as printers, and manage communication 
paths outside the network. 

In Section 3.12 you’ll find reference material on node server processes. Each server’s ref- 
erence pages contain the following information: 

• A description of the server process 

® Methods for starting, stopping, and reinitializing the server process 
® Information about configuration files 

® Information about options and arguments, and examples of their use 
® Special considerations 

Two servers, ns_helper and netmain_srvr, have interactive tools. The edns utility, which 
the system administrator uses with ns_helper, is described in the SysV Command Refer- 
ence. The netmain tool, which is used with netmain_srvr, is described in Appendix A. 

The reference information differentiates between creating servers on nodes with displays 
and those without displays (DSPs) because the two types of nodes sometimes require differ- 
ent start-up methods. 

3.5.4 Methods of Starting Servers 

Several methods are used for creating servers. The method used affects the server’s attrib- 
utes, whether it runs in the foreground or background, and whether it runs on a local or a 
remote node. 
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Starting Servers on a Local Node 

You can start servers on a local node in the following ways: 

• Inserting the server’s pathname in the /etc/rc, /etc/rc.user, or /etc/rc. local files. 
These files are executed as a part of start-up processing. This is the recom- 
mended way to start server processes. See ”Start-Up Procedures,” Section 3.8, 
for more information. 

• Executing DM create process commands from the DM input window. The DM 
cp (create process in a window), cpo (create process only), and cps (create proc- 
ess server) commands start server processes on a user’s node. Commands issued 
from the DM input window start server processes immediately. 

• Executing the /etc/server command. If the DM is not available, you can use this 
command to start server processes. This command has the following syntax: 

/etc/server server jiame server ^arguments & 

The /etc/server command executes the specified command under an SID of 
user, server. none. Appending an & causes the command to be run in back- 
ground mode, like the DM cps command. Without the &, the /etc/server waits 
for the command to complete. 

Note that you can also start servers by inserting the appropriate DM create process com- 
mands in the ‘node_data/startup[.fype] (for DM) and 4 node_data/startup.spm (for 
SPM) file. This method, however, is not recommended, since future windowing systems 
other than the DM will be available. 

Refer to the Domain Display Manager Command Reference for complete information about 
the DM commands cp, cpo, cps, and the shell command crp. 



Starting Servers on a Remote Node 

If the Server Process Manager (spm) is running on a node, you can create processes on 
that node from another location. (The spm runs on DSPs by default, so you can always 
create other servers or processes on a DSP from a remote node.) 

To create processes from a remote node, use the shell command crp (create remote proc- 
ess) . The crp command can take the cp, cpo, and cps local process commands as options 
to specify the attributes of the process created. For example the command 

$ crp -on //trout -cps /etc/ncs/glbd 

starts the process named glbd (in /etc/ncs) on the remote node named trout. 

Refer to the Domain Display Manager Command Reference for complete information about 
the DM commands cp, cpo, cps, and the shell command crp. 



Summary of Server Process Start-Up Methods 

Table 3-1 summarizes information about the ways to start servers. 
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Table 3-1. Server Process Start-Up Methods 



Server Start-Up 


Process runs in 


SID of Process 


Process runs on 


Method 


foreground or 


(id = node ID) 


local or remote 




background? 




node? 


Paths to DM command 
files inserted in a start- 
up file: 








cpo 


Background, runs whether 
or not anyone is logged in. 


log-in account SID 


Local 


cps 


Background, runs whether 
or not anyone is logged in. 


log-in account SID 


Local 


DM commands, entered 
in the input window: 








cp 


Foreground, ends on 
logout. 


log-in account SID 


Local 


cpo 


Background, ends on 
logout. 


log-in account SID 


Local 


cps 


Background, runs after 
logout (except for the 
siologin server). 


user, server, none. id 


Local 


Shell commands, if spm 
is running on the remote 
node: 








crp -cpo 


Background, runs after 
logout. 


log-in account SID 


Remote 


crp -cps 


Background, runs after 
logout. 


user-server, none, id 


Remote 


etc/server command 


Background, if the & op- 


user.server.none.id 


Local 


(can be used in the 


tion is used. Runs after 






event the DM is not 


logout (except for the 


If the -p option is 




available) . 


siologin server). 


used, SID will be 
the log in SID. 






Foreground if the & op- 
tion is not used. 







3.5.5 Naming Server Processes 

When you use the -n server jiame option with the server creation commands you can pro- 
vide a name for the server process. If you give a server process a name, you’ll be able to 
easily identify its server in the list displayed by the ps (process status) shell command. If 
you do not give the server a name, and it does not name itself by default, the operating 
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system identifies it with a process number. We recommend that you use names for servers 
(either the defaults that some servers provide, or a name of your choice). 

3.5.6 Using Shell Command-Line Features 

While most server processes that start in the DM command line don’t use shell command- 
line features, there are some that do. For such servers, the DM passes command-line stan- 
dard options to the server program. See the individual server descriptions in Section 3.12 
for information about servers that use command line features from the DM command line. 



3.5.7 Maintaining Existing Servers 

To check on the status of network server processes, use the shell command ps with the -e 
flag. The ps command lists all processes running on a node. The -n node option for ps 
shows the processes running on a remote node. Use ps and its options if you suspect that a 
server is not running. 

If the ps display does not show the server process, use the directions provided in the be- 
ginning of this section to restart the server. 

If ps does not list a server that you started, the server might not have started properly. 
ACLs that don’t allow access to the server process SID or to the ‘node_data directory can 
prevent a server from starting. If you use the ACLs that we provide in the ACL tem- 
plates, you should not experience this problem. However, if you change ACL entries and 
then a problem with server startup occurs, check the ACLs assigned to the server program 
itself (for example, /sys/alarm/alarm_server) and the ‘node_data directory of the node 
on which you want to start the server. Any person (or process) starting the server program 
must have Execute rights to the server program, and Read and Write rights to the 
‘node_data directory. 

Theps command sometimes lists a server process as running even though the server has 
stopped. If this happens, stop the server process explicitly with the sigp (signal process) 
command, then restart the process from the DM command line. To stop a server process 
running on a remote node, use the crp command to log in to the remote node, and then 
use kill to stop the process. Refer to the SysV Command Reference for information about 
the kill command. 



3,6 Establishing a Node’s Environment 

During software installation, the system administrator selects the Domain/OS environ- 
ment^) (that is, Aegis, BSD, or SysV) that will be available on the node. When the Do- 
main/OS software is installed on a node, you must determine the node’s primary environ- 
ment and system type. 
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3.6.1 The Node’s Primary Environment 

When multiple environments are installed on a node, one must be designated as the node’s 
default primary environment. A value called “ENVIRONMENT” is used to specify the en- 
vironment for all behavior except UNIX name resolution. ENVIRONMENT determines 

o Default key definitions 

Q User’s default shell if no shell is specified in the user’s registry entry 
o Default path definitions 

The ENVIRONMENT value can be aegis, bsd, or sys5.3. (Note that ENVIRONMENT is 
not an environment variable but is maintained as a per-process value.) If only one envi- 
ronment is installed, that automatically determines the value of ENVIRONMENT. No 
choice is needed and changing the value is not meaningful. 



3.6.2 The Node’s SYSTYPE 

SYSTYPE is an environment variable used to specify UNIX name resolution for many vari- 
ant links that use $(systype). Valid values for the environment variable are bsd4.3, 
sys5.3, or blank. 

3.6.3 The etc/environ File 

ENVIRONMENT and SYSTYPE values are specified in /etc/environ (which is actually a 
link to ‘node_data/etc/environ). For example, the file might say: 

ENVIRONMENT = aegis 
SYSTYPE = sys5 .3.3 

Valid ENVIRONMENT and SYSTYPE values are governed by what is installed on the 
node and the selection of the primary environment at installation time. Table 3-2 shows 
the valid combinations of primary environment, additional environments, ENVIRONMENT, 
and SYSTYPE. 
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Table 3-2. Relationships of ENVIRONMENT and SYSTYPE Values 



Primary 

Environment 


Additional 
Environment (s) 


Value of 
ENVIRONMENT 


Value of 
SYSTYPE 


Aegis 


None 


aegis 


blank 


Aegis 


BSD 


aegis 


bsd4.3 


Aegis 


SysV 


aegis 


sys5.3.3 


Aegis 


BSD 


aegis 


Choice of 




and 




bsd4.3 or sys5.3.3 




SysV 






BSD 


NA 


bsd 


bsd4.3 


SysV 


NA 


sys5.3 


sys5.3.3 



NOTE: If ENVIRONMENT is set to one of the UNIX values, SYSTYPE 

must correspond to that value. 

If the /etc/environ file is not found, the defaults are ENVIRONMENT = sys5.3 and SYS- 
TYPE = sys5.3. The value of ENVIRONMENT can be displayed by using the 
/etc/environment command; thus shell specific scripts can query the current environment. 



3.7 Establishing a User’s Environment 

If a node has multiple environments installed, users can choose to change the primary en- 
vironment in effect while they are logged in at that node. The file $ (HOME)/. environ, 
like the /etc/environ file, can contain lines specifying ENVIRONMENT and SYSTYPE. If 
this file is found during user log-in processing, the environment and system type specified 
are used as the user’s environment, as long as the specified environment is installed on the 
node. (If the environment is not installed, the node default environment is used.) 



3.8 Start-Up Procedures 

This section describes node start-up procedures, user log-in procedures, and related files. 

3.8.1 Node Startup 

The /etc/init program initiates node startup. This program first executes a Bourne shell 
script named /etc/rc (which, in turn, will execute other scripts) and then executes /etc/ttys 
(which also executes other scripts). Figure 3-5 illustrates node start-up procedures. Each 
script file in the start-up process is described following the figure. 
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mmmm 




Note: Solid lines (— ) indicate automatic operations. Dashed lines ( ) indicate paths where the 

preceding file invokes the following file (for example, /etc/rc invokes /etc/rc.user. 



Figure 5-5. Node Start-Up Files and Operations 



3.8,2 The /etc/rc File 

The /etc/rc file is a Bourne shell script executed as the first step in node startup by 
/etc/init. The /etc/rc file starts servers and other global processes as root. wheel. none. 
This file must also contain the commands that 

® Delete any files in the ‘node-data/tmp and ‘node_data/systmp directories 

• Start any servers that require root access rights 

• Invoke the /etc/rc. local and /etc/rc.user files (described in the next subsections) 
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Starting Servers in /etc/rc 

The /etc/rc file contains lines that invoke servers. When the file processes these invoca- 
tions, it first looks in the /etc/daemons directory to see if a file named for the server exists 
there. Since /etc/rc is owned by root and you must be root to edit it, /etc/daemons lets 
ordinary users (without root access) control which processes run from /etc/rc on their 
nodes. 

The /etc/daemons directory contains stub files named for the servers that should be 
started. Unless a file with the server’s name is in this directory, the server will not be 
started, regardless of whether it’s in the /etc/rc file. Node users can add or delete files to 
control the starting of server processes by /etc/rc. 

3.8.3 The /etc/rc.local File 

The /etc/rc.local file, invoked by /etc/rc during start-up processing, starts TCP/IP and its 
related servers. The commands in /etc/rc.local will execute with root access rights. Note 
that the /etc/daemons directory must contain a file named tcpd for the TCP/IP server to 
start. See Using TCP/IP Network Applications and Configuring and Managing TCP/IP for 
more information on TCP/IP. 

3.8.4 The /etc/rc.user File 

The /etc/rc.user file, invoked by /etc/rc during start-up processing, contains commands to 
start servers and other global processes that run as user.server.none, not as root. This file 
can be edited by users with other than root access, and does not need entries in 
/etc/daemons for the servers it starts. 



3.8.5 The /etc/ttys File 

The /etc/ttys file is executed by init during start-up processing. The /etc/ttys file starts 
the DM or SPM, getty processes for specified tty lines, and possibly window systems. 

Figure 3-6 shows the contents of a sample /etc/ttys file. 



console 


" /etc /dm_or_spm " 


apollo 


on 


secure 


ttyOl 


"/etc/getty dl200" 


dumb 


off 


secure 


tty02 


"/etc/getty std.9600" 


dumb 


off 


secure 


tty03 


"/etc/getty dl200 


dumb 


off 


secure 



Figure 3-6. Sample letclttys File 



The first entry starts the DM or the SPM, depending on whether the node has a display. 
The remaining lines in the file enable getty services on tty lines. DM and SPM startup, 
tty line initialization, and window system startup are described in the following subsections. 
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3.8.6 Display Manager Startup 



When the DM manager starts, it automatically executes ‘node_data/startup[.rype]* The 
. type option identifies the display type. Although you can use this file to start server 
processes, we recommend you use /etc/rc.user and /etc/rc. local instead. (If you do start 
processes in this file, the processes run regardless of log-in and log-out activity and run as 
user, server, none . ) 



Figure 3-7 shows the first lines in the start-up file we provide for the DN3000 mono- 
chrome node; the file is named ‘node__data/startup.l280bw. Corresponding start-up files 
for other types of displays draw the locations of the DM windows in different places, but 
otherwise, the files are similar. 



# STARTUP, /SYS/DM, default system startup command file for 1280x1024 monochrome 

# 

# Default is black characters on a white (or green) background. 

INV -ON 

# Window positions for the DMs input and output windows. 

# Do not comment these out. 

(692 .1011) dr; (1279 , 1023) cv /sys/dm/output 
(0 , 1011) dr ; (639,1023)cv /sys/dm/input 

(640. 1011) dr ; (692, 1023) cv /sys/dm/output ;pb 



Figure 3-7. Start-Up Script for DN3000 Monochrome (startup. 1280bw) 



3.8.7 Server Process Manager Startup 

If you start SPM on a node with a display, be aware that during the SPM startup, the 
‘node_data/startup.spm file will be executed. If this file contains the same commands as 
the DM start-up file, you will execute the same commands twice. If you regularly start 
SPM from a node with a display, ensure that all the node start-up commands are in the 
/etc/rc.user file. 

If SPM is running on a node (with or without a display), you can use the crp command 
from remote nodes to start processes on the node running the SPM. 

Although it is not recommended, you can start server processes in the SPM start-up file. 
The processes will run regardless of the node’s log-in and log-out activity and will run as 
user, server, none . 



Using ‘node_data/spm_control to Control Node Access 

The l node_data/spm_controI can prevent unauthorized users from creating processes on 
or logging into a node. If this file exists on the node running spm, all process creation 
and login requests are validated. Only users with a SID matching an entry in the file are 
allowed access; all others are rejected. If the file does not exist, all requests are allowed. 

Each SID entry should be in the following format: 
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person.group.org 



where a % character in a field matches anything. 

Figure 3-8 shows a sample ‘node_data/spm_control file. 

# allow access to all users 
%.%.% 

# allow access to all members of group grp 
%. grp.% 



Figure 3-8. Sample ‘nodejdatalspmjcontrol File 



The tty Line and Window System Startup 

The tty lines connect “dumb” terminals to workstations, either directly or through a mo- 
dem and telephone lines. The /etc/ttys file contains commands to start tty lines and win- 
dow systems. A sample line from the /etc/ ttys file is shown below: 

ttyOl "/etc/getty dl200" dialup on secure 

The line starts tty port 1, specifying that it will be monitored by the getty program, that it 
will run 1200 baud, and that only users with root access will be allows to access the line. 

The format for the command lines in the /etc/ttys file follows: 

ttyjine command terminal Jype status [window=” cmdjstring”] 

ttyjine The terminal’s entry in the device directory, /dev. 

command The command to execute for the line. This entry is usually 

getty. Getty is a program that performs such tasks as rec- 
ognizing the baud rate, reading the log-in names, and call- 
ing login. For command you can also specify the start-up 
file for a window system terminal emulator or some other 
server process. 

terminal Jype The type of terminal normally connected to that tty line, as 

found in the termcap database file. 

status A 2-entry option. For the first entry, specify on to enable 

the line; specify off to disable the line. For the first entry, 
to allow only root to log in on this line, specify secure. Do 
not quote this field. 

window =” cmdjstring” The cmdjstring argument is the pathname of the window 

system to start. If you specify a window system, it is 
started before any command is run for that line. 
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Tabs and spaces separate the fields. Use double quotes to enclose fields that contain more 
than one word (except the status field) . If you omit a field, its value defaults to null. 

NOTE: Previous releases used the tty line servers siomonit and siologin to 
enable tty lines. Although we recommend that you use the /etc/ttys 
file to enable tty lines, you can still use siomonit and siologin. To do 
so, disable all the entries for serial lines in /etc/ttys by setting their 
status to off. Then, see Subsection 3.12.5, “siologin and siomonit 
Line Servers,” at the end of this chapter for information on 
siomonit and siologin. 

3.8.8 User Login 

Figure 3-9 illustrates user log-in processing. 
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Note: Solid lines (— ) indicate automatic operations. Dashed lines ( — ) indicate paths where the 
the preceding file must call the following file. 



Figure 3-9. Node Start-Up Files and Operations 



User Log-In Processing 

1. When a user logs in to the node, the system: 

a. First looks in the user’s home directory for the $ (HOME)/. environ file. If 
this file exists, it sets the environment and systype accordingly (if the corre- 
sponding environment was installed on the node). 

b. Looks for a shell definition in the user’s registry entry. If one is not there, 
the appropriate shell for the current environment is used. 

c. Loads the key definitions based on the current environment. 
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2. The DM executes one of the following files: 

a. ‘node_data/startup_Jogin[.rype] — The DM first looks for this file. If it 
finds it, it executes the file. 

b. /sys/dm/startup_login[.fype] — If the DM cannot find the file in 
‘node_data, it uses this one. 

The startuplogin file is used to perform tasks that need to be invoked every 
time someone logs in to this node. These tasks include, specifying windows, creat- 
ing shells, and running user-specific scripts. The /sys/dm/startup_login file is 
supplied with the system. You should copy it to each node’s ‘node_data direc- 
tory. Then you can modify it specifically for each individual node. 

3. As supplied, the startup_login file invokes ~/user_data/startup_dm[.i:ype] . This 
file, which contains commands private to the user to be executed at his login, is 
not supplied with the system, but must be created. To cause it to be executed, 
remove the pound sign (#) from the last line in the /sys/dm/startup_login file. 
The line reads: 

# cmdf user_data/startup_dm[ . type] 

The SPM does not execute this script during remote logins. See Using Your SysV 
Environment for more information about this start-up file. 



Key Definitions 

When a user logs in to the node, the DM sets the default key definitions for the node ac- 
cording to the system type specified in /etc/environ or (if one exists) $(HOME)/. environ. 
Three sets of standard key definitions exist, one for each environment. When the user 
logs out, the DM resets the key definitions to the system type specified in /etc/environ. 

3.8.9 Log-Out Script Processing 

The DM processes log-out scripts. The log-out script must exist in either the /sys/dm or 
the ‘node_data directory, and the script must be named startup__logout[.rype], where 
.type is the appropriate display type suffix. You cannot start up new processes with the 
DM cp, cps, or cpo commands from this script. 



3.9 Start-Up File Summary 

Several types of start-up command files exist: files executed by the operating system at 
boot time, files executed by the DM and the SPM, and user files executed at log-in time, 
or when a shell is started. 

Table 3-3 lists the command files that can be used at these times. Some of these files run 
automatically; others must be specified in start-up files. The following subsections describe 
the files that execute when the DM or SPM start running and when you log in to the DM. 
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Table 3-3. Start-Up Files 



File 


When Run 


Comments 


/etc/rc 


System boot 


Runs automatically 


/etc/rc. local 


System boot 


Must be specified in /etc/rc 


/etc/rc. user 


System boot 


Must be specified in /etc/rc 


/sys/node_data [ .nodejd] /startup [ . type] 


DM startup 


Runs automatically 


/sys/node_data [.nodejd] /startup, spm 


DM or SPM startup 


Runs automatically on DSPs 


/sys/dm/startup_login [.type] 


User login 


Runs automatically 


/sys/node_data/startup_login [ .type] 


User login 


Runs automatically 


-/user_data/startup_dm[.fype] 


User login 


Must be specified in startup__login 



NOTE: A . type argument in a pathname represents a node display type iden- 
tifier: A . nodejd suffix to /sys/node_data represents the hexadeci- 
mal identifier of the diskless node for which the directory holds infor- 
mation. 

3.9.1 Node Display Types and Their Start-Up Files 

Because display formats differ, particularly in their pixel dimensions, different nodes re- 
quire different information in their start-up files. For example, the length of the DM win- 
dows vary among display types. For this reason, each node and DM login start-up file has 
several different versions, one for each display type. The display type is indicated by a suf- 
fix added to the start-up file name. Therefore, /sys/node_data/startup.l91 is the DM 
start-up file for nodes with an 800-pixel by 10242-pixel landscape display. Table 3-4 lists 
the display-type suffixes and indicates the node models to which they apply. 
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Table 3-4. Start-Up File Suffixes 



File Suffix 


Node Types 


.spm 


Server nodes 


.1280bw 


Monochrome DN3000 and DN4000 


.1280color 


DN580 


.191 


DN300, DN320, DN330, DN460, DN550, DN560, 
DN570, Color Domain 3000 and Domain 4000 


.color 


DN660 



The installation procedures copy all versions of each start-up file on a node. This proce- 
dure ensures that any node can be a partner for any type of diskless node. Similarly, it is 
useful to have multiple versions of the DM log-in files if you are likely to log in on nodes 
with different display types. 

3.9.2 Templates for Start-Up Files 

The installation procedures automatically create several start-up template files. Table 3-5 
lists the files. 



Table 3-5 . Start-Up File Templates 



File 


Comments 


/sys/dm/startup__templates/startup[.fype] 

/sys/spm/startup_templates/startup.spm 
/etc/templates (directory) 


Copied to /sys/node_data.node_Jd 
for diskless nodes 

Copied to /sys/node_data.rtOGte_/d 
for diskless nodes 

Copied to /sys/node_data/etc for 
diskless nodes 
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The files in the /sys/dm/startup_templates and /sys/spm/startup_templates directories 
serve two purposes: 

• They are master copies of the DM and SPM start-up files. You should edit these 
master copies only if you are making changes that should propagate through to all 
nodes in the network and to all nodes to be added in the future. If you are 
changing the start-up files for individual nodes, edit the copy created for the spe- 
cific node, not the master copy. 

• They are used as the source for the files copied by netman whenever it creates a 
/sys/node_data.rt 0 </e_/d directory for a diskless node. For more details on this see 
“Administering Diskless Nodes.” 

3.9.3 Start-Up File Format 

The start-up files contain DM or shell commands. If the file is a shell script, it normally 
starts with one of the following lines to specify the shell that will interpret the commands: 

#!/bin/sh For the Bourne shell 

#!/bin/csh For the C shell 

#!/bin/ksh For the Korn shell 

The default versions of the start-up files that are created when you install the SysV soft- 
ware contain most of the commands that you are likely to need. However, most of these 
commands are commented out in the files with a pound sign (#). You must delete the 
pound sign from the start of the line to allow the command to execute. For example, to 
allow the netman process to run whenever the node boots, uncomment the following line 
in the /sys/node_data[.rcode_W]/startup[.0 , pe] file by deleting the pound sign: 

# cps /sys/net/netman 

NOTES: The DM, the Server Process Manager (spm), and the shell are 

all case sensitive. Use lowercase characters when referring to 
system commands and files. 

Changes that you make in a start-up file do not take effect until 
the next time the file is run at system boot. 



3.10 Administering Diskless Nodes 

There is no apparent difference between working on a diskless node and a disked node. 
However, before you can use a diskless node, you must configure the node and start the 
processes that support the diskless node’s operation. The following subsections describe the 
rules and techniques for managing diskless nodes and their partners. The last subsection 
describes a procedure for configuring a diskless node’s partner. 
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3.10.1 Diskless Node Operation 



When a diskless node displays the log-in prompt, all the programs required for its opera- 
tion are in place. While Using Your SysV Environment gives a complete description of disk- 
less node bootstrap operation, the following summary indicates what happens after you 
power on a diskless node in NORMAL mode. 

1. The diskless node’s Mnemonic Debugger broadcasts a message requesting a volun- 
teer disked node partner. 

2. Each disked node running the netman program listens for such a “request for vol- 
unteer” broadcast. The disked node answers the request if the requester’s hexa- 
decimal node ID is in the disked node’s /sys/net/diskless_list file. 

3. The diskless node loads netboot, its version of the operating system boot program 
from the partner, and proceeds with the bootstrap operation. 

4. If the / /partner/ sys! node jdata.disklessjiodeJd directory does not exist, for exam- 
ple, if the diskless node has never booted from this partner, the netman program 
creates the directory and copies the node startup [.type] file from the 
/sys/dm/startup_templates directory. 

5. The diskless node’s DM executes the commands in the 
//partner/sys/nodejdata.disklessjiodeJd/startup[.type] file. 

6. The diskless node runs in the same manner as a disked node, using the partner 
node’s disk for its system software. 



3.10.2 Establishing Diskless Nodes and Their Partners 

A diskless node’s partner node provides the system software and disk services for the disk- 
less node. The partner does not necessarily store any of the diskless node user’s files. Each 
partner node must run the diskless node server, netman. Partners can be nodes with, or 
without displays. Nodes without displays are DSPs. 

A partner node must have the correct system software for the diskless node type. For ex- 
ample, if the diskless node is a DN570 and the partner node is a DSP90, the partner node 
must have both a /sau2 directory and a /sau5 directory. Similarly, the partner’s /sys direc- 
tory must have any microcode files required by the diskless node. 

Each diskless node has its own /sys/node jdata.disklessjiodeJd directory on the partner 
node. The *node_data directory on each diskless node resolves to 

/sys/node_data .diskless jiodejd. If you change diskless node partner assignments, delete 
the /sys/nodejdata.disklessjiodejd directory from the original partner’s /sys directory. 

The home directories of diskless node users can be located on any node in the network, 
and do not have to be on the diskless node’s partner node. Whenever possible, locate the 
home directories on the same loop as the diskless node. If a diskless node has one or 
more regular users, their personal log-in start-up scripts, user_data/startup_dm[.^ype], 
should be in their home directories. 
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Specifying Partners 

A disked node can be a partner to one or more diskless nodes. You control the assign- 
ment of diskless nodes to partners through the disked node’s /sys/net/diskless_list file, 
such as the one shown in Figure 3-10. The disked node will volunteer to be a partner for 
any diskless node whose node ID is in the disked node’s diskless_list. 



# This is the diskless list for the network server on node 6b2d. 

# 

# The first token in each line of this file is examined by netman 

# when it receives a network bootstrap volunteer request. If the 

# token is a valid node ID, then netman will volunteer to help 

# that node when it calls. Lines that do not begin with a valid 

# node ID will be ignored. The use of the comment line 

# character is recommended. 

# 

# The nodes that this file authorizes netman to volunteer help for 
if are: 

3f4 
eff21 
4d7 6 



Figure 3-10. Sample ! sys /net / diskless Jist File 

Choose the partners for diskless nodes carefully. For example, a partner must be in the 
same network loop as the diskless node; then, if you switch the loop out of the rest of the 
network, the diskless node can still function. 

NOTES: If you put a diskless node’s node ID on more than one diskless 

list, you cannot predict which node will become the partner 
when the diskless node boots. As a result, the diskless node’s 
*node_data directory and the contents of that directory, could 
change whenever the node reboots. Therefore, you must config- 
ure the diskless node correctly on each possible partner node. 

(The next subsection provides more details.) 

If you use names for diskless nodes, do not change the name of 
the / sys/ node jdata.disklessjiodeJd directory to /sys/ 

nodejdata.disklessjiodejiame. Remember, a diskless node 
name is not valid in a pathname. You must specify the diskless 
node ID to accurately access this object. 

When you boot a diskless node you can request a specific part- 
ner node. See “Requesting a Specific Partner,” in Section 
3.10.3. 



The /sys/node_data.node_id Directory on New Partners 

If a diskless node’s partner does not have a /sys/node_data .nodejd directory when the 
diskless node boots using the partner, netman automatically creates one. If this directory 
does not contain the minimal set of files required by the diskless node to operate, netman 
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creates them. The netman utility also copies the startup [.type] file from the partner’s 
/sys/dm/startup_templates or /sys/spm/startup_templates directory. 

Providing a New Partner for a Diskless Node 

Use Procedure 3-1 to configure a partner for a new node, change a partner for an existing 
node, or to provide an additional partner for an existing node. If a service representative 
installs a diskless node, he or she creates a partner for the node; you might want to use a 
different partner. 
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Procedure 3-1. Providing a Permanent Partner for a Diskless Node 



Task 1: 



Task 2: 



Task 3: 



Task 4: 



Determine the diskless node’s ID 

If the node is new, the node identification slip lists the node ID. 

If the diskless node currently has a partner, you can determine the ID by entering 
the following command at the diskless node: 

$ /com/ netstat 

The node ID of this node is eff21. 

Log in to the partner node 

If the partner has a display, log in at the partner node. 

If the partner does not have a display, you can create a remote shell on the part- 
ner by using this command: 

$ /com/crp /sys5.3/bin/start__sh -on / /partner -me 

Add the diskless node to the partner’s list of authorized nodes 

Edit the partner node’s /sys/net/diskless_list file, and add the diskless node’s 
node ID to the list. 

If you are changing partner nodes, delete the diskless node’s ID from the old 
partner node’s /sys/net/diskless_list file. Also delete the old partner’s 
/sys/nodejdata.diskless_node_id directory. 

Start netman on the partner node 

If the partner node is running netman already, go on to Task 5. 

If the partner node is not running netman, do the following: 

1. Remove the pound sign (#) from the following line in the partner’s 
/sys /etc/rc.user file: 

# if [ -f /sys/net/netman ] 

# (echo "netman\c : O/dev/console 

# /sys/net/netman & 

# fi 

The netman server will now start automatically whenever the partner reboots. 
If you had crp’d to the partner node, you could start netman as follows: 

$ /etc/server/sys/net/netman & 
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Task 5: 



Task 6: 



Task 7: 



2. Start the partner node’s netman server. (By doing this, you do not have to 
reboot the partner.) 

If you are at the partner node, enter the following command at the DM com- 
mand prompt: 

Command: cps /sys/net/netman 

To start netman from a remote node, enter the following command: 

$ crp -on node -cps /sys/net/netman -n netman 
(You must use this command even if you used the crp command in Step 2.) 



Limit the size of the partner’s memory pool (optional) 

You can limit how many memory pages are left available for diskless node paging 
requests using the netsvc command. (Be aware, however, that this command af- 
fects the memory pool size for all situations in which files are used remotely on 
your node.) 

To limit the size of the partner’s memory pool, type: 

$ netsvc -p [pool_size] 

where pool_size is the maximum number of memory pages that will be available for 
diskless node paging. 

If you don’t use this command, all of the partner’s memory is available for paging 
requests from the diskless node. 

Name a diskless node (optional). 

If you are installing a new diskless node, you can give it a name. Skip this task if 
the node already has a name. 

If you do not use ns_helper on your network, enter the following command: 

$ ctnode nodejiame nodejd 

If you do use nsjhelper at your site, enter the following: 

$ ctnode nodejiame nodejd -root 

After you finish this procedure, catalog the node on the network. 

Create node start-up and configuration files 

1. Create the diskless node’s /sys/node_data.noflte_/d directory by entering the 
following command at the partner node. 

$ mkdir / sys/ node jdata. node Jd 
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where node id is the diskless node’s ID. 



The netman tool will copy the /sys/node_data/startup/.0>pe7 hie from the 
partner to the diskless node’s / sys/nodejiata. node Jd directory (where type is 
the type of display on the diskless node, not the partner). The netman tool 
copies the file from the partner’s /sys/node_data directory, or from the 
/sys/dm/startup_templates directory (for diskless nodes with displays) or 
/sys/spm/startup_templates directory (for diskless DSPs). 

NOTE: The netman tool does not copy the start-up file until you try booting 
the node (see Task 9) . If you are changing the partner of an existing 
diskless node and you care about the start-up file, copy the start-up 
file manually. 

Edit the /sys/nodejdata.nodejd/startup[.type] file to configure the diskless node. 



Task 8: Log off the partner node 

Task 9: Reboot the diskless node 

You can now start or restart the diskless node. 

If you are changing an existing diskless node’s partner, enter the following DM 
command to log off and shut down the operating system. 

Command: shut 

The Mnemonic Debugger prompt (>) appears on the screen. Enter the following 
reset command: 

> re 

Press <RETURN> twice. 

The PROM identifier appears, followed by the PROM prompt. Restart the operat- 
ing system by entering the following command: 

> ex domain os 

The node now restarts, using the new partner node; you can now log in. 



3-34 



Administering Nodes in the Network 





3.10.3 Managing Diskless Nodes and Partners 



You should evaluate your diskless node partner assignments from time to time. Distribute 
assignments in a way that does not degrade the performance of either partner. The net- 
main_srvr process, the network maintenance server, and the netmain interactive tool, 
along with the netsvc shell command, can help you to manage partner assignments. The 
netmain__srvr does not work in IEEE 802.3 (ETHERNET*). Note that diskless nodes and 
their partners must be on the same network. 



Diskless Node Management Commands 

Netmain_srvr collects information about the number of diskless nodes assigned to any 
partner. The netmain interactive tool formats the performance data so that you can iden- 
tify nodes providing more than their share of resources to diskless nodes in the network. 
For a detailed description of netmain_srvr and netmain, see Appendix A. 

Sometimes the partner node is referred to as the paging partner because it performs the 
paging services for the diskless node. The diskless node copies information (operating sys- 
tem, global data, etc.) in 1024-byte pages from its partner as needed. You can use the 
netsvc command limit the size of the partner’s paging pool available to the diskless node 
(or any node) using Procedure 3-1, Task 5, described previously. 

Whenever a diskless node cannot communicate with its partner, it displays a message to 
that effect. You will see this message if the partner stops running the operating system be- 
cause of an intentional shutdown or system crash. Problems with the network can also 
cause the diskless node to display the message. Once the partner node is rebooted or the 
network is back up, use CTRL/F to refresh the screen on the diskless node and eliminate 
the messages. You must reboot the diskless node whenever its partner node reboots. 



Warning of a Partner Shutdown 

It’s good practice for the administrator of a partner node to notify diskless node users of 
intended shutdowns. Use the send_alarm or /etc/wall command to notify users of shut- 
downs. For example, if your are shutting down your disked node, the following command 
will warn all diskless nodes that use your node as a partner: 

$ send_alarm ’Partner node disked is shutting down in 2 min. Please log out.’ -mydi 
Requesting a Specific Partner 

If for some reason a diskless node’s regular partner is not available, the diskless node can 
request as its partner another disked node that runs netman, even if that node does not 
have the diskless node on its partner list. You can also use this procedure to boot a disked 
node as a diskless node, which you might need to do if, for example, the node’s system 
software is corrupted. This is a temporary measure, however; you should not use this pro- 
cedure in place of the disklessjhst file. Use the following steps to boot a diskless node by 
requesting a specific partner: 



ETHERNET is a registered trademark of Xerox Corporation. 
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1. Shut down the node if it is not already shut and reset the node with another part- 
ner. To do so, boot the diskless node in SERVICE mode or, if the node is run- 
ning the DM, use the DM shut command to enter the Mnemonic Debugger. 

2. Enter the following command when the Mnemonic Debugger prompt (>) appears: 

> di n nodejd 

where nodejd is the hexadecimal ID of the partner node you are requesting. 

3. Enter the following command to restart the node. 

> ex domain os 



3.11 Node Troubleshooting 

If a node doesn’t appear to be operating correctly in the network, you can try to diagnose 
the problem in a number of ways. This section does not attempt to be exhaustive, but it 
does outline some common faults that occur and how to correct them. 

Check Connections and Power 

Check the brightness control on the monitor. Make certain that cables are attached cor- 
rectly and securely. Make sure the power is on. 

Check LEDs 

If the node has LEDs (such as the DN3000 series), see if they’re active. If they are, sus- 
pect problems outside the node, perhaps with the network. 



Try to Communicate with the Hung Node 

Try to list the entry directory of the hung node. For example, if the node name is 
chinook, try the following command line from another node on the same network. 

$ Is //chinook 

If you receive the message “name not found,” try recataloging the node name, as shown in 
the example below, and then retry the listing. If you receive an “object not found” mes- 
sage, make sure you’re not on a loop that’s been switched out of the network. 

$ ctnode hexjd chinook -r -1 

Is the hung node running diskless? If so, the problem might be that the partner node has 
crashed, or that temporary network problems have disturbed the communication between 
the partner and the diskless node. Remember, too, that a diskless node can have a name, 
but doesn’t have an entry directory, so if you Id a diskless node name as if it were an en- 
try directory (for example, //diskless), you will receive the message “object not found.” 
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Check Processes 



You can check the process running on the node in one of two ways. Either use the crp 
command to log in to the node and run the ps or dspst process status commands, or use 
the -n nodejspec option with either the ps or dspst command to look at the processes. 
Look for exceptionally heavy network traffic or for a process taking up an inordinate 
amount of CPU time. 



3.12 Server Reference Information 

This section describes the following servers: 

• Alarm Server — alarm_server 

• Mailbox Server — mbx_helper 

• Diskless Node Server — netman 

• Tablet Server — spbl 

® Serial I/O Line Servers — siologin and siomonit 

• Clock Server — cron 

® Write Server — writed 

You can obtain online help for any server by typing the following line, substituting the 
name of the server for server jiame, 

$ help server jiame 

Chapter 2 provides reference information on the Server Process Manager and the netmain 
server. 

3.12.1 The Alarm Server: alarm_server 

The Alarm Server (/sys/alarm/alarm_server) alerts you by popping a small alarm window 
on the screen and sounding an alarm. 

Run the Alarm Server as a background process by starting it with the DM command cpo. 
Usually, you’ll start the Alarm Server from an entry in a start-up file. 

The Alarm Server can report on potential disk overflow, network problems, netmain_srvr 
observations, and brief messages from other users. Each condition is checked every four 
minutes by default, or at an interval that you set with the -period option. 

By default, an alarm is accompanied by a distinctive tone pattern. You can disable the 
audible alarm or have all alarms alert you with a single short beep. 

Alarm messages appear in windows of default sizes, accompanied by standard sound pat- 
terns. The first alarm window appears near the top left-hand corner of the screen. Use 
command options to alter the default window positions. A “pad closed” message appears at 
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the bottom of the alarm window when the alarm is complete. Note that if you inadver- 
tently press CTRL/Q in the window before the message appears, you will kill the Alarm 
Server. 

Certain optional software packages also use the Alarm Server. See the release notes and 
documentation for any optional software you have purchased for details about the alarm 
server’s operation with those products. 

Starting the Alarm Server 

To start the Alarm Server, enter the following from the DM command line: 

Command: cpo /sys/alarm/alarm_server -[options] 

The server process begins immediately and ends at logout. 

To start the Alarm Server from a start-up file, include the following line in the start-up 
file. You’ll have to log out and log in again for the server to start. 

cpo /sys/alarm/alarm_server -[options] 

The Alarm Server names itself “alarm_server” by default, so you don’t need to specify the 
-n option with the cpo command. 



Configuration Files 

To execute Alarm Server options from a configuration file, create a file using the format 
illustrated in Figure 3-11. 



-disk 75 
-hw 

-nmsrvr //netmain_srvr_node 
-belli 



Figure 3-11. Sample Alarm Server Configuration File 



Alarm Server Options and Arguments 

To receive alarms about any of the standard Alarm Server events, specify the event with 
one or more options described below. The default event reports are indicated by (D) . 
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—disk [__full] [nn] 



Posts an alarm when the disk containing the node’s / directory is more 
than nn percent full. If you omit nn , alarm__server uses a default value 
of 95 percent full (5 percent free space). If you do not delete anything 
from the disk, or if the full-disk condition recurs, alarm_server notifies 
you again. After two notifications of a full-disk condition, alarm__server 
does not notify you again for at least one hour, even if the condition per- 
sists. 

Default if omitted: Do not post disk-space alarms. 

-hw[_fail] Posts an alarm when some node on the network detects network hard- 

ware problems (as seen in the “last ring hardware failure” report from 
the netstat -1 command). The netstat output lists the last hardware fail- 
ure report detected on the network, whether it is new or not. The Alarm 
Server posts alarms only when there is a new report, indicating a current 
problem. 

Default if omitted: Do not post a network problem alarm when there is 

a new hardware failure report. 



-netmain [pathname ...] 

Enables alarms from netmain_srvr observers. The pathname { s), if speci- 
fied, represent text files containing lists of nodes that run netmain_srvr. 
If you don’t specify a file for pathname , the Alarm Server uses the file 
~/user_data/alarm_server.netmain_srvr_list. 

The files should contain node names or hexadecimal node ID numbers 
on different lines or separated by spaces on the same line. Comments in 
these files start with a left brace ({ ) or a pound sign (#) and run to the 
end of the line. 

The Alarm Server reads these files only when it starts up. If you add or 
delete node names in these files after the server is running, changes do 
not take affect until the next time the server starts up. 

Default if omitted: Do not enable alarms from netmain_srvr observers 

on node lists. 



-nm_srvr node_spec [...] 

Enables alarms from netmain_srvr observers on the node(s) specified 
with node_spec> which is a hexadecimal node ID or node name. 

Default if omitted: Do not enable alarms from netmain_srvr observers 

specified in the command line. 

-nonetmain (D) Prevents the Alarm Server from checking for observer alarms from the 
netmain_srvr program. 
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-nets 

-nonets (D) 
-msg (D) 

-nomsg 

-belli 



-nobell 



Notifies you when a network disappears from your internet or appears in 
your internet. This option is useful only in Domain internet environments. 

Suppresses alarms describing changes in the internet topology. 

Allows the alarm server to receive messages from the send_alarm pro- 
gram. 

Prevents the alarm server from receiving send_alarm messages. 

Sounds a single short beep for any alarm, instead of the usual distinctive 
tone pattern for this alarm type. The -nobell option overrides -belli. 

Default if omitted: Use distinctive tone patterns for each alarm type. 

Suppresses audible alarms for all alarm types. 

Default if omitted: Sound audible alarms. 



-p[eriod] nnn Checks each alarm detector every nnn minutes, where nnn is a decimal 
number greater than or equal to 1. 

Default if omitted: Check each alarm detector every four minutes. 



-v[ector] dx [dy] 

Separates alarm windows by dx and, optionally, dy, where dx is the dif- 
ference (in pixels) between the horizontal coordinates of each alarm win- 
dow and dy is the difference between the vertical coordinates. Specify dx 
and dy as decimal integers. For example, you might want the top left cor- 
ners of successive alarm windows to be 0,0 for the first window, 20,20 for 
the second window, and so on; to do so, use the option -v 20 20. (Use 
the -w option to specify the location of the initial window.) 

Default if omitted: vector 235 0 



-w[indow] initx [inity [width [height]]] 

Sets the screen position of the first alarm window and the size of the 
alarm windows. 



Default if omitted: window 1 1 225 100 



Examples 

The following example causes the Alarm Server to post a nonaudible alarm when the disk 
is 98 percent full (2 percent free space): 

$ cpo /sys/ alarm/ alarm server -disk 98 -nobell 

The following example causes the Alarm Server to post alarms when the disk is 90 percent 
full, when there is a new hardware failure report message, and whenever there is an 
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observer report from the netmain_srvr running on node ID “ffff5.” The command also 
sets the screen position of the first alarm window position to be the upper left-hand corner 
of the screen. 

$ cpo /sys/alarm/alarm_server -disk 90 -hw -nm_srvr ffffS -w 5 5 

This next example make use of an options file that you’ve created (in this case 
~/user_data/opts) to control the Alarm Server. This command also uses the -n option to 
name the Alarm Server process “alarms”. 

$ cpo /sys/alarm/a!arm_server ,:;i ~/user_data/opts’ -n alarms 



Special Considerations 

Occasionally the Alarm Server prints a warning message about a file called 
.../alarm__server.msg__mbx as it starts up. Such a message can come from several 
sources. Often the problem is caused by incorrect protection about the mailbox used by the 
server process (see mbx_Jielper, the Mailbox Server) . The Alarm Server can usually 
change the protection on its message mailboxes automatically, but it will sometimes need 
your help. 

The protection on two files must allow the mbx_helper program Read (r) and Write (w) 
access. Make sure that the files ‘node_data/alarm_server.msg_mbx and 
~/user_data/alarm_server.msg_mbx both allow Read and Write access to 
user.server.none. 



Related Information 

Information about using the Alarm Server with netmain_srvr is provided in the section on 
the netmain_srvr process in Chapter 2. 

Additional information about using the Alarm Server is available with certain optional soft- 
ware packages. For example, the Domain Software Engineering Environment (DSEE™) is 
an optional software package that uses the Alarm Server. If DSEE is installed on your sys- 
tem, see the DSEE manuals for additional information. 

3.12.2 The Mailbox Server: mbxjhelper 

The Mailbox Server (/sys/mbx/mbx_helper) assists processes on different nodes that com- 
municate using mailboxes. This server must run on any node that sends or receives mail- 
box communications across the network. 

The mbxjhelper process is automatically started by any Apollo servers or programs that 
need the server to operate correctly. To send a message via the send_alarm command, 
both the sending and receiving nodes must have an mbxjhelper process running. For the 
sending node, if it doesn’t already have an mbXjhelper running, the sendjalarm com- 
mand will start one. At the receiving node, the alarnijServer process will start an 
mbXjhelper process if one doesn’t already exist there. 

You only need to start an mbx_helper explicitly, with a DM cp command or from a start- 
up script, if you are running a non-Apollo server that requires mbXjhelper to operate. 
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For further information about starting mbxjhelper from programs, see Programming With 
Domain/OS Calls . To provide network services to a node, enable mbxjhelper by remov- 
ing the pound sign (#) from the appropriate start-up file on that node. 



Special Considerations 

In a secure network, a mailbox receives its permissions from the directory in which it is 
created. The ACL templates we supply ensure that server processes can have access to 
each other. If you do not use the templates we supply, be certain that the persmissions you 
use allow clients on remote nodes to access a node’s mbxjhelper. If user programs have 
difficulty accessing mbxjhelper, be certain that users know how to use mbXjhelper in a 
secure network. See Programming With DomainlOS Calls for more information. 

You cannot change a mailbox’s permissions while the mailbox is in use. 

3.12.3 The Diskless Node Server: netman 

The netman (/sys/net/netman) process manages requests from diskless nodes for access to 
the operating system. Diskless nodes, having no place to store the necessary operating sys- 
tem files, use a disked node’s disk for storage. 

The netman process, running on a disked node, receives “request for volunteer” broad- 
casts from diskless nodes attempting to boot. The netman process looks in its /sys/net/ 
diskless_list for a diskless node’s hexadecimal ID. If the ID appears in the list, the disk- 
less node can read, from netboot, the disked node on which netman runs. To control the 
distribution of disked node resources in the network, specify which diskless nodes can use 
a given disked node as a partner. Do this by placing diskless node IDs in the partner’s 
/sys/net/disklesSjlist. 

If a diskless node does not have its own 'nodejbata.diskless ,node_id directory when it 
boots, netman will create one for it from a template in the disked node’s 
/sys/dm/startuPjtemplates directory. See the “Start-Up Procedures” section earlier in this 
chapter for more information about node start-up directories. 

The netman server runs as a background process from a start-up file. The command line 
that executes netman is in the default /sys/dm/startuPjtemplate script that arrives with 
your system. Remove the pound sign (#) at the beginning of the command line to enable 
the process. The netman server will execute from the start-up script when the node is re- 
booted. You may start the process from the DM command line as shown in the next sec- 
tion. 



NOTE: We do not recommend that you run netman on an internet routing 
node. Network traffic between a diskless node and the routing node 
would compete with the internet traffic on the routing node, slowing 
both the internet traffic and the response time of the diskless node. 



Starting and Stopping netman 

To start netman from the DM command line, enter the following command: 
Command: cps /sys/net/netman 
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The server process begins immediately and persists after logout. Another way to start net- 
man is to uncomment the following line in the appropriate start-up file for the disked 
node: 

# cps /sys/net/netman 

The server process begins when the node is booted, and continues under normal conditions 
until it is intentionally stopped with the shell command sigp, as shown: 

$ sigp netman -q 

With both start-up methods described above, the process stops running if the node is shut 
down intentionally or because the system crashes. Restart the process if it stops running by 
rebooting the node, or by entering the cps command from the DM command line. 



Special Considerations 

For a temporary fix, you can use netman if you disked node malfunctions. To do this 
you must shut down and reboot your node diskless. The netman tool allows any disked 
node to continue functioning even if its disk becomes nonfunctional. 

To complete this temporary procedure, do the following: 

1. Determine the node ID of any node running netman. (You may want to start the 
netman process on a disked node in the same loop as the now diskless node.) 

2. Use the DM command shut on the node that you want to boot diskless. 

3. Then type the following at the Mnemonic Debugger prompt: 

> re 

> di n nodejd {nodejd is the node ID of the node running netman} 

> ex domain_os 

Network Partner ID nnnn 

In this procedure netman bypasses /sys/net/diskless_list. You don’t need to edit the list to 
get the node back in the network. When you use this procedure, netman creates a 
‘node_data/startup[.fype] file for the node with disk problems. 

3.12.4 Tablet Server: sbpl 

The Tablet Server (/sys/dm/sbpl) supports tablets that conform to the binary output mode 
used by Summagraphics Corporation tablets. To use a tablet, enable the Tablet Server sup- 
port program in the appropriate start-up file for the node. The server process sends a con- 
trol character to the tablet bit pad. An operating system program then provides the actual 
bit-pad support. The process started in the start-up file stops running when the operating 
system has taken control. 
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Starting the Tablet Server 

To start the Tablet Server, uncomment the following line in the appropriate start-up file: 

# cps /sys/dm/sbpl /dev/sio2 1 

To use a different SIO line, change the “2” in the command to the desired number. The 
letter “1” indicates the mode and sampling rate selector that is sent to the tablet. You may 
change this mode to one of the other modes described in the Summagraphics Corporation 
Bit Pad One User's Manual (Form 64) . 



Special Considerations 

The bit-pad support is internal to the operating system, and the server mentioned here 
only enables the operating system support and then stops. Therefore, the ps command 
does not show a process for the bit pad. To check on a bit-pad process, use the tctl com- 
mand on the SIO line to which the bit pad is connected, and check that -bp_enable is 
true. The bit-pad support program is running properly if the tctl output contains the fol- 
lowing line. 

bp_enable: true 

3.12.5 siologin and siomonit Line Servers 

Previous releases used the siomonit and siologin SIO line servers to allow you to connect 
a “dumb” terminal to a Domain workstation, either directly or via modem and telephone 
lines from another location. Although we recommend that you use the /etc/ ttys file to 
enable SIO lines, you can still use siomonit and siologin if you want. 

The SIO line server processes are 

• siologin — SIO line login (/sys/siologin) 

Invoked by siomonit. It must be a manager within the log-in protected subsystem. 
Siologin is the process that directly manages user login. 

• siomonit — SIO process monitor (/sys/siomonit) 

Typically invoked as a background server process from a start-up file. 

Below, we describe the procedure used to connect terminals to Domain workstations. Be- 
fore you can use this procedure, set up the necessary configuration files and enable the 
server processes siomonit and siologin, described in the next sections. 

To connect a node’s SIO lines to a dumb terminal and/or modem, follow these steps: 

1. Disable the SIO lines in the /etc/ttys file. To do so, specify off in the status field 
for all but the first entry in the /etc/ttys file. 
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2. Use the shell command tctl to display the SIO line configuration. The default val- 
ues for the SIO lines are 

9600 baud 
No parity 

Eight bits per character 
One stop bit 

3. Change the SIO line configuration to conform to the modem or terminal configu- 
ration parameters. This may be done in a shell command file run by siologin 
when it starts. Alternately, change the terminal or modem configuration parame- 
ters according to the manufacturer’s instructions to conform to the SIO line con- 
figuration. 

4. Enable the siomonit server with the proper configuration files and arguments. 

The siomonit process starts the siologin process. 

5. Connect the terminal or modem to the SIO line. Use the cable and directions sup- 
plied with the terminal or modem. If you have connected a modem, the line pa- 
rameters on the terminal and modem at the remote site must match those you 
specified at the Domain workstation. Connect the modem to the telephone. When 
you are ready to log in, signal the SIO line by pressing <RETURN> on a locally 
connected terminal. From a remote terminal, dial the number of the phone line 
connected to the node’s modem. 

When you are finished using a local or remote terminal, press CTRL/Z (or the character 
you have defined as the EOF character using tctl) to end the siologin process. On a local 
terminal, you are disconnected. On a remote terminal, you are disconnected from the 
node and the phone connection is broken. 



3.12.5.1 The SIO Line Log-In Server: siologin 

The siologin process uses the following command line syntax: 

siologin devjiame [[-dialin] [-n name] prog [ argument ...]] 

Each siologin server process waits for a carriage return character from a terminal con- 
nected directly to the SIO line, or a Data Carrier Detect (DCD) signal from a modem if 
the -dialin option has been specified. The modem generates this signal when it answers a 
dial-in from a remote terminal. 

Upon receiving the character or signal, siologin invokes the operating system log-in se- 
quence. If the sequence is successful, siologin logs the user in and starts a program. You 
specify the program with the prog specification. The default option starts the shell 
command-line interpreter program /com/sh. The devjiame argument, which must be 
specified, is the SIO device descriptor pathname. Other options, if specified, must precede 
prog and its arguments. The siologin subsystem process stops when the user logs out (usu- 
ally with CTRL/Z). 

The siologin command-line syntax appears as an argument list in a file used by siomonit 
(usually *node_data/siomonit_file) . We describe the meaning of siologin options and ar- 
guments in the following section. 
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The siologin process looks for a start-up file 4 node_data/startup_sio.sh and, if it exists, 
executes it as a shell command file, by passing it the SIO line number as an argument. For 
example, for /dev/sio2: 

/com/sh ‘node_data/startup_sio.sh 2 

The sample file, /sys/siologin/startup__sio.sh, provided with the system includes the tctl 
command shown below to ensure that the SIO line is not locked through some previous 
failure: 



ulkob /dev/sio2 "1 -f 



The siologin Options and Arguments 

The siologin process accepts the following arguments: 

devjiame (required) 

The SIO device descriptor pathname, in the form /dev/siox, where x is 
the number of the SIO line to which the terminal or modem is con- 
nected. Use SIO line numbers 1, 2, or 3 for nodes with three SIO lines; 
use SIO line numbers 1 or 2 for nodes with two SIO lines. 

prog A program for siologin to start after the login is complete. If omitted, the 

default invokes /com/sh to start the shell command-line interpreter. 

args Arguments for the program specified in prog . 

The siologin process accepts the following options: 

-dialin The SIO line connection is remote. If the line is remote, siologin asks 

for an access password before invoking the log-in sequence. The access 
password is a single string read from ‘node_data/siologin_access. For 
remote lines, siologin waits for a carrier detect signal to initiate the oper- 
ating system log-in sequence. It disconnects the line after the invoked 
program returns. (If the connection is local, siologin waits for a <RE- 
TURN> before beginning the log-in sequence.) The siologin process logs 
invalid log-in attempts in the file ‘node_data/siologin_Iog. 

-n name Specifies the name to give the siologin process. (Takes precedence over 

the option cp -n when siologin is created through the DM command in- 
stead of through the siomonit server process.) 



Special Considerations 

When you use the -dialin option to specify remote access, you must specify an access 
password in the file ‘node_data/siologin_access. Create the file by entering a password as 
a left-justified single string in the file’s top line. 

Siologin logs successful and unsuccessful log-in attempts from remote terminals. It creates 
the file *node_data/siologin_log, which reports the SIDs of users who log in successfully, 
and provides error messages describing unsuccessful log-in attempts. You should monitor 
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‘node_data/siologin_log and periodically delete it, or delete old entries, since it is not 
self-limiting in size. Figure 3-12 shows a sample log file. 



Thursday, February 14, 1985 13:40:52 

** Bad (or no) access code in N node_data/siologin_access ** 
Thursday, February 14, 1985 13:40:52 

*# Hanging up phone ** 

Tuesday, February 19, 1985 15:52:29 

Invalid login attempt by: jones 
Tuesday, February 19, 1985 15:53:37 

Invalid login attempt by: jones 
Tuesday, February 19, 1985 15:53:48 

jones. dev. mktg.Sde logged in 
Tuesday, February 19, 1985 15:58:19 

Caller logged out. 



Figure 3-12. Sample ‘node jlatalsiologin Jog File 



To operate, the siologin server must have manager status in the login protected subsystem 
(see Using Your SysV Environment for more information about the subsystem.) The soft- 
ware installation procedures give siologin manager status. If the server does not operate 
properly when siomonit starts it, display its subsystem status as follows: 

$ /subs /sys/siologin/siologin 

If you receive the following message, siologin has the proper manager status: 

"/sys/siologin/siologin" is a login subsystem manager 
"/sys/siologin/siologin" is a file subsystem data object 

If, however, you receive the following message, the siologin process has lost its manager 
status: 

"/sys/siologin/siologin" is a nil subsystem manager 
"/sys/siologin/siologin" is a file subsystem data object 

To reassign manager status to siologin, you must log in with a sys_admin account and 
type: 

$ ensubs login 

$ subs /sys/siologin/siologin login -mgr 
$ CTRL/Z 



3.12.5.2 The SIO Process Monitor: siomonit 

The siomonit process supports repeated logins over SIO lines, independent of any log-in 
or log-out activity at the node terminal. To enable siomonit, create a file that describe the 
attributes of each siologin manager that the siomonit server process should start. The 
siologin processes started by siomonit are called its child processes. 

The file passed to siomonit contains argument lists. Each argument list has the form of the 
siologin command line described previously. The siomonit process invokes a separate 
siologin process for each argument list in this file. A maximum of three argument lists 
(one per SIO line) can be given. Comments can be included in the file with a pound sign 
(#). 
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Starting siomonit 

To invoke siomonit from the DM command line, enter the following: 

Command: cps /sys/siologin/siomonit siomonitjfilename 

The server process begins immediately and continues after logout. 

We recommend this start-up method if you use siomonit or siologin only occasionally. 

This is also the way to start the process after you log in or if the process dies. Be sure the 
SIO lines are configured correctly by using the tctl command. Usually the 
siomonit _ filename argument is ‘node_data/siomonit_file. 

To start siomonit from a start-up file, uncomment the line that reads as follows: 

# cps /sys/siologin/siomonit -n siomonit N node__data/siomonit_f ile 

Be sure this line appears after any lines in the start-up file that set environment variables. 

The server process begins when the node comes online and continues across logins and 
logouts at the node terminal. We recommend this start-up method if you use siomonit and 
siologin frequently. 

Signaling the siomonit Process 

Sometimes you will want to signal siomonit once you have started it. You might do this, 
for example, after you make changes to an argument list or if you add a new argument list 
to the file siomonit__file. 

To make siomonit reread the argument file and execute the process again, signal siomonit 
with an asynchronous quit fault (sigp -q) . This is the default option of the sigp command: 

$ sigp siomonit 

The siomonit process goes back to its argument file and redoes whatever it finds there. 
Note however that siomonit will never stop an active child process for a given SIO line, 
even if you have changed the argument list for that SIO line. You must stop the child 
process. This will also cause siomonit to reread the siomonit_file. To stop siomonit, send 
it a stop fault (sigp -s). 



Restarting siomonit 

If the siomonit process stops running, restart it from the DM command line (or by reboot- 
ing the node). Check the siomonit_!og file first, to determine why the process stopped. 

Sample siomonit_file 

The siomonit_file name argument lists take the form: 

[-repeat] siologin_arg_list 

The arguments in the siomonit_file are as follows: 
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-repeat 



Configures siomonit to restart this siologin process after a user logs out. 
For example, when a user of an SIO line logs out, no one else can log in 
to that line unless this argument is in effect. It signals siomonit to restart 
the siologin process. This argument should be the first one given. 



siologin_arg_list 

The list of siologin arguments and options described in the section on 
siologin. Arguments are passed to siologin unvalidated; however, the first 
argument must be /dev/siox. The siomonit process reads the argument 
file over again each time a child process stops, when a user logs out, or 
when it receives a quit fault. 

Figure 3-13 shows a sample ‘node_data/siomonit_file. You can include comments by 
placing the pound sign (#) at the beginning of a line. 



if sample file for using siomonit 
if 

# Configure the sio lines and invoke siomonit with a line like this 

# in 'node_data/startup (or /sys/dm/startup) : 

if cps /sys/siologin/siomonit -n siomonitor 'node_data/siomonit_f ile 

# 

if Put the sio line startup file in 'node_data/startup_sio. sh. 

# 

tf and put a file like this one in 'node_data for the node to be used. 

if 

if watch sio. lines 1 and 2 and keep them available for siologin: 
if line 1 is a dial up line: 

-repeat /dev/siol -dialin -n siologinl /com/sh -f -c user_data/startup_sh 
# line 2 is a local connection: 

-repeat /dev/sio2 -n siologin2_local /com/sh -f -c user_data/startup_sh 

if 

if up to three siologin arg lists like the ones above may be included, one 
if for each sioline (only two will work for DN300's) . 
if 

ff This file is re-read by siomonit each time it re-invokes an siologin 
if process or when it receives a signal via: sigp siomonit 



Figure 3-13. Sample 'node _data! siomonit Jile File 

For each argument it finds in the list, siomonit invokes the siologin program, 
/sys/siologin/siologin siologin jargjlist 



Special Considerations 

Use the log files ‘node_data/siomonit_log and ‘node_data/siologin_log to help you debug 
siologin or siomonit server problems. Figure 3-14 shows a sample of a siomonit_log file. 
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Tuesday, February 19, 1985 9:28:13 

Quit fault. Restarting any dead processes... 

Tuesday, February 19, 1985 11:05:56 

** Process didn't stay alive for 15 secs: ** 

/sys/siologin/siologin /dev/siol -n siologinl 
Tuesday, February 19, 1985 11:08:15 

** Received stop fault. Closing up shop. ** 

Tuesday, February 19, 1985 16:34:53 

Restarted process: /sys/siologin/siologin /dev/siol -n siologinl 

Tuesday, February 19, 1985 9:18:02 

* Couldn't open command input file s node_data/siomonit_f ile . Status 1010015 * 



Figure 3-14. Sample ‘node _data! siomonit Jog File 



Often, the failure of an siologin process to stay alive can be caused by a locked SIO line 
(/dev/siox). For example, when a user on a locally connected terminal does not end the 
session with CTRL/Z, the SIO line to that terminal remains locked. To free up the line, 
use sigp -q to prod siomonit into trying again. After you free the line, you may want to 
include ulkob A 1 -f in your ‘node_data/startup_sio.sh file. 

If siomonit terminates and its child processes do not also terminate, the child processes 
are, in effect, orphans. The existence of the orphans interfere with siomonit’s attempts to 
restart new child processes when it restarts. Siomonit itself never stops a child process, its 
own process, or an orphan process. However, siomonit will not be notified when an or- 
phan process terminates. Instead, if siomonit detects an orphan’s existence, it wakes up 
every 15 minutes to see if the orphan has stopped. If the orphan process has ended, 
siomonit restarts the siologin process as directed in its argument list. Should this occur, a 
user may have to wait 15 minutes before completing the siologin process. 

3.12.6 The Clock Server: cron 

The cron server executes commands prestored in command files in the 
/usr/spoolcron/crontabs, directory. The crontab files are submitted via the cron tab 
command. Additionally, you can submit commands which are to be executed only once 
via the at command. 

The cron server examines the crontab and at command files during process initialization 
and whenever the files are changed via crontab or at. 

You should start cron from the /etc/rc start-up file to ensure it has root access. Once 
started, cron does not stop until the node is brought down. (Note that like all servers 
started from /etc/rc, you must also create a file named “cron” in the /etc/daemons direc- 
tory to start cron. See Section 3.8, “ Start-Up Procedures” for information on server 
startup.) 

See the manual pages for crontab and at for details on how to create the crontab files 
read by cron. 
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3.12.7 The Server for the Write Program: writed 



The writed server is used by the write(l) program. The writed server enables allows 
communication between two nodes by copying lines from one node to another. To enable 
this type of communication, writed must be running on both the sending and receiving 
nodes. 

The writed server starts an mbxjhelper automatically when it is invoked. See the writed 
man pages for more information on using writed. 

You should start writed from the /etc/rc start-up file to ensure it has root access. (Note 
that like all servers started from /etc/rc, you must also create a file named “writed” in the 
/etc/daemons directory to start writed. See Section 3.8, “Start-Up Procedures,” for in- 
formation on server startup.) 



3.13 Log-In Monitoring 

SysV provides node log-in monitoring for log-in attempts via 
© The Display Manager 

© A window 
© The spm 
® An SIO line 

When you configure login monitoring, you can specify whether records of successful and 
unsuccessful logins or only unsuccessful logins should be kept. You can also specify the 
sources of the logins you want to monitor. 

3.13.1 Configuring the Log-In Facility 

The file ‘node_data/login_log.config specifies which attempts to log in should be recorded 
and the log file in which to store this information. The default log file is 
‘node_data/login_Iog. 

The ‘node_data/login_log.config file contains a line for each type of login that can be 
monitored. The sample line, shown below, is for logins via the Display Manager: 

# -display [-inv_only] 

To enable log-in monitoring, uncomment the appropriate lines. If you don’t uncomment 
any lines and if you don’t create the log file, no logging will take place. To record only 
invalid log-in attempts, remove the square brackets from around -inv_only. 

To specify a log file other than ‘node_data/Iogin_log, uncomment the following line and 
replace path_name with the name of the log file you want. 

# -file path_name 
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3.13.2 The Log-In Facility Log File 



Information about the logins is stored in a log file. The default log file is named 
‘node__data/login_log. Note that the log file grows without bounds and must be managed. 



For each login, the log file contains 

• The date and time of the login 

• An indication of whether the login was from the Display Manager, a window, the 
SPM, or an SIO line using siologin 

® The user ID under which the login was initiated 

© An indication of whether or not the login was successful (unless you specify that 
only unsuccessful logins should be recorded) 

Figure 3-15 is a sample log file. 



Friday, October 30, 1987 16:12:45 window odonnell.osdev.r_d invalid login attempt 
Friday, October 30, 1987 9:30:09 window jjdjd invalid login attempt 
Friday, October 30, 1987 13:13:33 display doug.osdev.r_d.5FE logged in 
Friday October 30, 17:36:26 window root. staff_sr9. none. 5FE logged in 
Friday, October 30, 1987 17:42:39 display doug.osdev.r_d.5FE logged in 

Friday, October 30, 1987 17:59:28 sio odonnell.osdev.r_d logged in connected to device: /dev/siol 
Monday, November 2, 15:09:50 sio odonnell.osdev.r_d.5FE logged out from device: /dev/siol 
Monday, November 2, 15:15:50 sio intruder invalid login attempt on device: /dev/sio2 



Figure 3-15. Sample Log-In Monitoring Log File 



3.13.3 Log File Protection 

To protect the log file from unauthorized modification, you should give it fairly restricted 
protection. If you do this, you must also stamp the file as a log-in protected subsystem 
data object to allow the log-in program to open it and make entries. You should also pro- 
tect the login_log.config file appropriately. 
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The following protection settings are suggested for the log file: 

Acl for login_log: subsystem login object 

Required entries: 

root.%.% pwrx — 

% . sy s_admin . % pwrx — 

% . % . none [ ignored] 

%.%.% — r-k- 

(Note that, in the table, the k for %.%.% makes it unnecessary to protect the ‘node_data 
directory.) In some circumstances, you may want to add an entry that gives the node 
owner full rights to the file or make the node owner the owner of the file. 

□□ 

□□ 
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Creating and Maintaining the Registry 



The Domain/OS registry consists of a database of account information and associated 
software that enables you to store and manipulate account information, thereby controlling 
access to the computers on your network. The registry database can be replicated so that 
it resides on several nodes in a network or internet. A server must run on each of these 
nodes. 

This chapter focuses on the network registry, a registry of account information that is 
accessible throughout your network or internet via registry servers. In addition to the 
network registry, you can create local registries residing and operating on individual 
nodes. Ordinarily, local registries are used only as a backup when the network registry is 
unavailable. Chapter 4 also provides the following information: 

o Overviews of the registry and the registry server 

o A discussion of network registry administration and local registries 

© A description of how to operate small networks with local registries 

Through the rest of this chapter, the term “registry” refers to the network registry (data- 
base and software). The term “local registry” always appears in full. 



4.1 Registry Software 

The registry server manages changes to the data and maintains consistency among the 
replicas of the registry database. Any node must communicate with a registry server when it 
requires access to registry information—for instance, when it checks an attempt to log in. 
Nodes use the Location Broker, a component of the Network Computing System™, to 
locate registry servers. 

Figure 4-1 shows a sample network configuration, including a master registry node, a 
replica registry node, and normal nodes. The figure indicates where the registry server 
(rgyd) and the Location Broker daemons (glbd and llbd) are running, where replicas of 
the registry database reside, and where local registries reside. 
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Slave Registry Node 



Figure 4-1. Registry Components 



4.1.1 The Registry Server 

The registry server, /etc/rgyd, can run either as a master or as a slave. There is exactly 
one master server on a network or internet. All other servers are slaves. 

The master server handles operations that change the database (for example, adding an 
account or changing a password) and propagates the changes to the slaves. Either the 
master or a slave can handle operations that only read the database (for example, verifying 
a password when a user logs in) . Thus, the master server must be available for any editing 
operation, but a slave server suffices for lookup operations. Section 4.4 describes how the 
servers maintain consistency among the databases. 

While it runs, the registry server, whether a master or a slave, maintains its database in 
virtual memory. The server periodically saves the database to a copy that resides on disk. 
Because the copy on disk is not always up to date, there are special procedures you should 
follow for backing up the registry database and for restoring the database from a backup 
tape. These procedures are detailed in Sections 4.8, "Routine Manitenance,” and 4.10, 
"Troubleshooting. ” 

We recommend that, in an internet, at least one registry server exist on every network. We 
discuss considerations for configuring servers in Subsection 4.6.1. 

4.1.2 Tools for Editing and Administering the Registry 

Nearly all editing of the registry database must be done with edrgy. (The only exceptions 
are certain operations that users can perform on their own accounts, such as changing 
passwords.) The master registry server must be available to receive changes. 
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The rgy_admin tool administers the registry server. It can list, reset, replace, and delete 
replicas of the registry. It also performs special functions such as changing the master 
registry site and reinitializing a slave registry server. 

The cvtrgy tool enables you to run SR10 and pre-SRIO registries simultaneously on a 
network or internet. See Making the Transition to SR10 Operating System Releases . 

If you are creating a Domain internet, you can use rgyjmerge to merge data from regis- 
tries that have operated in partitions of the internet. See Managing Domain Routing and 
DomainlOS in an Internet . 

If your Domain systems coexist with other UNIX systems, you should ensure that name 
and account information is consistent between the Domain/OS registry and the UNIX 
password and group files. The import_passwd tool, described in Section 4.11, helps you 
to establish consistency. 

4.1.3 Location Broker Software 

As we mentioned earlier, nodes use the Location Broker to locate registry servers. Two 
daemons, the Local Location Broker daemon (llbd) and the Global Location Broker 
daemon (glbd), are essential to Location Broker operation and hence to operation of the 
registry. A glbd must run on at least one node in a network. In an internet, each network 
must have at least one glbd. An llbd must run on all registry server nodes and on all glbd 
nodes. Managing the NCS Location Broker provides information about starting and running 
these daemons. 



4.2 The Registry Database 

The registry database stores information about names, taccounts, and policies. Table 4-1 
shows the general categories of data in the registry database. 



Table 4-1 . Registry Database Categories 



Names 


Accounts 


Policies 


Persons 


SIDs 

(pgo triplets) 


Registry Policy 


Groups 
(member lists) 


Passwords 


Organization 

Policy 


Organizations 
(member lists) 


Home Directories 






Log-In Shells 





All of these registry database objects can be edited with the edrgy command. 

4.2.1 Names 

Names establish the existence of individual persons, groups, and organizations within the 
registry. Identical names can exist in different domains of the registry database— there can 
be a person, a group, and an organization with the same name. 
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Persons can have a primary name and one or more aliases; an alias is an alternate name 
for a person. Groups and organization have only primary names, not aliases. 

Associated with each primary name are a UID (Unique Identifier) and a UNIX number 
that the operating system uses as identifiers. A primary name or alias can also have a 
fullname. The operating system doesn’t use fullnames but provides them for easy recogni- 
tion by users. 

Unique Identifiers 

The operating system associates each primary name with a (UID) consisting of a node ID 
and a time stamp. When printed as a text string, a UID has two parts separated by a 
period, as in 38eddel7.50007c5f. 

The association between UID and primary name is fundamental to the protection of files 
and directories in your network. If you destroy this association (for example, by deleting 
the name from the database), you effectively “orphan” all files owned by that UID. You 
can use edrgy to “adopt” the orphaned files (that is, associate the UID with a name). 

Numbers 

A number, in the context of the registry database, is a decimal identifier associated with a 
primary name. Numbers are analogous to UNIX user and group IDs, so we sometimes 
refer to them as UNIX numbers or UNIX IDs. They exist for UNIX compatibility and are 
used mainly by UNIX programs. 

If you convert a registry from SR9 to SR10, the conversion tool adds numbers to the 
registry database; if you are building a new registry database, you assign numbers when you 
create names. If your Apollo systems share files with other UNIX systems, you should 
ensure that names, UNIX IDs, and account information are consistent between the 
Domain/OS registry and the foreign systems. Subsection 4.6.5 contains more information 
about establishing uniform UNIX IDs. 

Aliases 

Aliases enable you to establish several accounts that have different home directories and 
passwords but share the same access rights to files. You can use edrgy to change an alias 
into a primary name and a primary name into an alias. Although it is possible to create an 
alias without an existing primary name, you ordinarily create a primary name entry before 
you create any aliases for that name. Groups and organizations can have only primary 
names, not aliases. 

Fullnames 

A fullname is a text string associated with a person, group, or organization name. The 
fullname typically describes or expands the name. For example, the person name owright 
could have the fullname Orville Wright, and the organization name rd could have the 
fullname Research and Development. 

4,2.2 Accounts and Subject Identifiers 

Accounts define who can log in to the computers on your network. An account associates 
a person, a group, and an organization. Each account includes information that the operat- 
ing system needs when a user logs in, such as a password and a home directory. 
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Subject Identifiers 



The operating system identifies each account by a Subject Identifier (SID) consisting of a 
person name, a group name, and an organization name, separated by periods, as in 
rubinstein. pianists. none. We use the terms pgo and pgo triplet as synonyms for SID. 



In some SIDs, a percent character (%) can appear as a wildcard in place of a name. For 
instance, mozart.%.% matches mozart. pianists. none and mozart.symphonists. classical. 
Wildcards are not allowed in account SIDs, but they are allowed in the SIDs that specify 
ownership of registry data. 



Other Account Information 

For each account, the operating systems stores the following information in the registry 
database: 

© An SID, for example, grappelli. violinists. jazz. 

© An abbreviation for the SID, for example, grappelli or grappelli. violinists. At 
login, a user need only enter the abbreviation to specify the SID. When you add 
an account, edrgy automatically assigns the shortest unique abbreviation unless 
you specify otherwise. For example, if the SID babar. elephants. none already ex- 
ists with the abbreviation babar, a new account for babar. kings. none will have 
the abbreviation babar. kings. 

© An encrypted password. When a user attempts to log in, the operating system 

prompts for the password, encrypts the text string that the user enters, and checks 
the result against the encrypted string stored in the database. 

® A flag that determines whether the account is valid. If an account is not valid, the 
operating system will reject any attempt to log in on that account. 

® A home directory. 

© A log-in shell. 

© Miscellaneous information. This is a text string that typically describes the user of 
the account. If the person specified in the SID has a fullname, the person’s 
fullname is concatenated with the account’s miscellaneous information to form the 
gecos field in the /etc/passwd file. 



4.2.3 Reserved Names and Accounts 

We supply several reserved names and accounts with the operating system, for use by 
various system operations. You cannot change the UIDs and numbers associated with 
reserved names. 



Table 4-2 lists these names and accounts. 
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Table 4-2. Names , Accounts , and SIDs 



Person 


Group 


Organization 


Person. Group. Organization 


admin 

bin 

daemon 

lp 

root 

sysjperson 

user 

uucp 

none 


backup 

bin 

daemon 

locksmith 

login 

mail 

none 

server 

sys 

staff 

sys_admin 

sys_proj 

wheel 


apollo 

none 

sys_org 


none. none, none 

user. none. none 

sy s_person . none . none 

admin . none .none 

da emon . none . none 

bin.bin.none 

lp. bin. none 

uucp . daemon, none 

root, staff, none 



In addition to those required for reserved accounts, we supply the following memberships: 
the person user is member of the groups backup and sys_admin and the organization 
apollo; the person bin is a member of the group mail, and the person root is a member 
of the groups bin and sys. 

4.2.4 Groups and Organizations 

Here we describe some features that are specific to groups and organizations. 



Passwords 

Each group or organization can have a password. In the SysV environment, if a group has 
a password, a user who is not a member of the group can acquire its privileges by invoking 
the newgrp command and entering the correct password. 

Many sites opt not to assign passwords for groups and organizations. 



Membership Lists 

Each group or organization has a membership list containing the person names of all its 
members. In order for you to create an account, the specified group and organization must 
contain the specified person in their membership lists. 

For example, in order for you to create an account mahler.symphonists.none, the group 
symphonists and the organization none must have the person mahler in their membership 
lists. (If you are the owner of the group symphonists and the organization none, edrgy 
automatically adds mahler to their membership lists so that you can create the account in 
one step. If you are not the owner of symphonists and none and mahler is not already 
on these lists, edrgy issues an error. We describe owners of registry objects in Subsection 
4.2.7.) 

Project Lists 

BSD UNIX systems associate each user process with not one group but a set of groups. 

This set consists of the group specified for the user in /etc/passwd and any other groups of 
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which the user is listed as a member in /etc/group. The user always has the access rights 
that accrue from membership in every group in the set. 

Domain/OS creates such a set of groups, called a project list, if you have the PROJLIST 
environment variable set to true. The project list consists of all groups of which the user is 
a member. If PROJLIST is not set, only the pgo of the user process controls access to 
files. Thus, Domain/OS allows you to choose either BSD or SysV behavior. 

By default, PROJLIST is set automatically if your SYSTYPE is bsd4.3. 

Not every group can be included in a project list. The reserved group locksmith, for 
instance, has a property that prohibits its inclusion in project lists. When you create a 
group with the edrgy command, the group is set up to allow inclusion in project lists unless 
you explicitly specify otherwise. If you change the properties of a group to disallow its 
inclusion in project lists, you cannot undo the change. 

4.2.5 Policies 

The registry database includes policies that regulate the following aspects of accounts and 
passwords: 

® Password expiration date 

® Password lifespan (how long a password remains valid before it must be changed) 
o Account lifespan (how long an account remains valid) 

© Minimum length of passwords 

© Whether a password can consist entirely of spaces 

© Whether a password can consist entirely of alphanumeric characters 

You can use edrgy to set any of these policies for the registry as a whole or for a particu- 
lar organization. If a policy is set both for the registry and for an organization, the stricter 

policy applies. For example, if registry policy specifies a minimum password length of six 
characters and policy for the rd organization specifies eight characters, the account 
bell. comm. rd must have a password at least eight characters long. 

By default, when the registry is created, policies are at their most permissive— passwords 
have no expiration date, passwords and account have unlimited lifespans, there is no 
minimum password length, and passwords can consist entirely of spaces or entirely of 
alphanumeric characters. Many sites set one or more of these policies to be stricter. 
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4.2.6 Properties 



The registry database also includes the following properties: 

• The owner of the registry as a whole 

• The owner of each name domain 

• Whether UNIX restrictions are enforced 

• Whether UNIX restrictions are met 

• Whether the registry database is read-only 

You can use edrgy to set any of these properties. 

UNIX restrictions are met if no names exceed eight characters, all accounts have the p 
(person only) abbreviation, and all passwords are valid for vanilla UNIX systems. If UNIX 
restrictions are enforced, all data in the registry database must meet the restrictions. (Re- 
served names and accounts are excepted; they do not affect whether UNIX restrictions are 
met and they are not affected if the restrictions are enforced.) 

4.2.7 Owners 

Every object in the registry database has an owner who is allowed to modify that object. 
There are also owners for the registry as a whole and for each of the three name domains 
(person, group, and organization). 

Owners are represented by SIDs. These SIDs can include wildcards. 

Default Ownerships 

All ownership information is contained in the registry database and can be edited via 
edrgy. When the registry is first created, the initial data, the name domains, and the 
registry as a whole are all owned by %.%.%. By default, all data added via edrgy is owned 
by %.sys_admin.%. 

Some sites assign owners other than the defaults for registry information. You can use the 
change command in edrgy to assign ownerships for any names. You can use the prop 
command to assign ownerships for the three name domains and for the registry as a whole. 
To specify the default owner for data added via edrgy, issue the defaults command at the 
beginning of every edrgy session. 

At most sites, it is simplest to have one owner for the registry and all of its data. This 
owner can be the unrestrictive SID %.%.%, a restrictive SID such as %.sys_admin.%, or 
an SID created specially for registry administration such as %.registry_admin.%. However, 
some sites prefer to have different owners for different data. A common scheme is to use 
organizations as administrative domains. For example, you can assign %.sales__admin.sales 
as the owner for the sales organization; this SID will have control over the membership list 
for sales and thereby will have control over all accounts of the form %.%. sales. 

Rights of Owners 

The following list summarizes the operations that can be performed by the owner of the 
registry and by owners of registry objects: 
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Q The owner of the registry can change registry policies and properties, change the 
owners of name domains, and use the rgy_admin and rgy_merge tools. 

o The owner of a name domain can add entries in that domain. For instance, the 
owner of the person domain can add persons. 

o The owner of an organization can add or delete members, change properties such 
as the password and the fullname, change policies for that particular organization, 
or delete the organization. If the owner of organization deletes person from the 
membership list, any accounts for person.%. organization are also deleted. If the 
owner deletes organization itself, accounts for %.%. organization are deleted. 

o The owner of a group can add or delete members, change properties such as the 
password and the fullname, or delete the group. If the owner of group deletes per- 
son from the membership list, accounts for person. group. % are also deleted. If the 
owner deletes group itself, accounts for %. group. % are deleted. 

o The owner of a person can change properties such as the fullname, delete the 
person, or add an account (provided the person is a member of the specified 
group and organization). Deleting person also deletes accounts for person. %.%. 

o Account information such as the password and fullname can be changed by any 
user of the account. 

Q The owner of any registry object can change the owner of that object. (An owner 
can actually “give away” ownership.) This also applies to ownership of the registry 
as a whole. 

Any of these registry operations can also be performed by a root.%.% or %. locksmith . % 
account, provided the user is logged in at the master registry node. 



4.3 The /etc/passwd, /etc/group, and /etc/org Files 

UNIX systems store information about accounts in the files /etc/passwd and /etc/group. 
Domain/OS provides these files and, in addition, an /etc/org for information about organi- 
zations. 

In Domain/OS, the passwd, group, and org files cannot be directly edited. Changes to the 
registry database are made with edrgy or with specialized utilities such as /com/chpass and 
/bin/passwd. The registry server reflects all changes in the passwd, group, and org files as 
well as in the registry database. The server updates these files periodically, whenever it 
saves its database from memory to disk. 

Each registry server, whether master or slave, maintains its own versions of the passwd, 
group, and org files in its copy of the registry database. On all nodes, the files in /etc are 
specially typed file system objects; when a user requests access to one of the files, the 
operating system finds a version of the file at one of the registry server nodes. 

UNIX system calls such as getpwent(3) access the version of the registry database that 
resides in memory at a registry server node. These calls do not use the passwd, group, 
and org files at all. Thus, though the files in /etc are not always current with the registry 
database in memory, the asynchrony is harmless. 
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The rest of this section describes the format of the passwd, group, and org files in 
Domain/OS. See also the reference documentation for passwd (5), group (5), and org(5). 

4.3.1 The /etc/passwd File 

The passwd file contains one line of text for each account in the registry database. Colons 
divide each line into seven fields, as follows: 

account-name:encrypted-password:user-ID:group-ID:gecos:home-directory:login-shell 

The account-name is the SID of the account, abbreviated if possible. The user-ID and 
group-ID are the UNIX numbers of the person and group in the account SID. The gecos 
field is the concatenation of the person’s fullname and the account’s miscellaneous infor- 
mation. (Subsection 4.2.2 explains the SID, miscellaneous information, and other account 
data.) 

The passwd file can include several entries for one person if the person has several ac- 
counts, as in the following excerpt: 

arnold : QB4mmrONj s/szD : 15586 : 98 : Ken Arnold : //anarres/arnold : /bin/csh 
arnold . unix : ZcdWqJGsemkYJn : 155 86 : 3 8 : Ken Arnold : //anarres/arnold : /bin/csh 

If an account is invalid, its entry in the passwd file will contain the text string *NOACCT* 
where the encrypted password would ordinarily appear. 

4.3.2 The /etc/group File 

The group file contains one line of text for each group in the registry database. Colons 
divide each line into four fields, as follows: 

group-name:encrypted-password:group-ID:membership-list 

The group-ID is the UNIX number of the group. The fourth field is a list of person 
names, separated by commas. Thus, part of a group file could look like this: 

dds : : 78 : emart in , pato , phi , pj 1 , mishkin , molson , mk 
debug : : 211 : gordon , cas , gkk 
demo: : 68 : 

In the group file, each entry occupies one line of text. 

4.3.3 The /etc/org File 

The org file contains one line of text for each organization in the registry database. Its 
format is the same as that of the group file: 

org-name:encrypted-password:org-ID:membership-list 

The org- ID is the UNIX number of the org. Part of an org file could look like this: 
inti : : 9 : j imk 

legal : : 10 : barker_c , olesen_d , ponte_l , f az io_p , rossini_r , peter , \ 
lewis j , dacierjp , lynch_p , egoldman , barbara 
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In the org file, a backslash (\) at the end of a line indicates that the membership list 
continues on the next line. 



4.4 How the Registry Database is Replicated 



As we mentioned in Section 4.1, the registry database can be replicated. In addition to the 
database managed by the master server, you can create database replicas managed by slave 
servers. Replication of the registry database can enhance performance and reliability, 
especially in an internet. 

The registry uses “weakly consistent” data replication: the data in every replica of the 
database are always available, though the data in slave databases are not always up to date. 
The replication mechanism ensures that all replicas of the database will converge to the 
same set of information while remaining available for lookup by system software and by 
applications. 

Figure 4-2 shows part of a replicated registry configuration. The master server and one of 
the slave servers are pictured. Each server manages a database of name and account 
information and a replica list containing the network address of each host that runs a 
registry server. The master server also manages a propagation queue containing informa- 
tion that it must propagate to the slaves. 




Registry 

Client 



i 


Lookup 

Operations 


Registry 


Server 


Database 


Replica List 


latest 

update: 


hostl 


TS2 


host2 

host3 



rgyd@host1 (master) 



rgyd@host2 (slave) 



Figure 4-2. Registry Server Operation 
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As the figure shows, edrgy makes changes only to the database, and rgy___admin makes 
changes only to the replica list; these changes can be made only through the master server. 

When you change any information in the database or in the replica list (for example, by 
adding an account, or adding a replica) the master server enters the changed information, 
called an update, in its copy of the database. It marks both the database and the update 
with a time stamp. 

The master server places the update in the propagation queue and attempts to propagate 
the update to each slave server on its replica list. If propagation of an update to one of the 
slaves does not succeed on the first attempt, the master server retries periodically until it 
succeeds. The master server always propagates updates in chronological order, according to 
their time stamps. It keeps track of which updates are pending propagation to which slaves. 
When an update has propagated to all the slaves, it is removed from the propagation 
queue. 

In Figure 4-2, for example, the update with time stamp TS3 awaits propagation to the 
slave server at host2. Propagation of the updates with time stamps TS1, TS2, and TS3 to 
the slave server at host3, not shown, is still pending. 

If the master server loses communication with a slave server for a long time, the master 
server will reinitialize the slave server, giving it a fresh copy of the entire database, when 
communication is restored. 



4.5 How the Registry Database is Stored on Disk 

Each registry server, whether master or slave, maintains a working copy of its database in 
virtual memory and a permanent copy on disk. All lookups and updates operate on the 
copy in virtual memory. The server uses the copy on disk to initialize the copy in memory 
when it starts up. 

When a master server receives an update from a utility such as edrgy or when a slave 
server receives an update from the master, the server applies the update to its database in 
virtual memory and also saves the update in a log file on disk. Updates accumulate in this 
log file in chronological order. When a server restarts (for example, when a server node 
boots), it initializes its database in memory from the database on disk and then it “replays” 
the updates from the log file. This mechanism ensures that no updates are lost when a 
server node is shut down. 

Each registry server periodically saves its entire database from virtual memory to disk. The 
database is stored in the directory /sys/registry. When it performs a disk save, the server 
clears the log file. 

Sections 4.8, “Routine Maintenance” and 4.10, “Troubleshooting,” give procedures for 
backing up the registry database and for restoring the database from a backup tape. 



4.6 Setting Up the Registry 

This section describes how to set up the registry. Note that several of the procedures in 
this section must be performed by the root user. 



4-12 Creating and Maintaining the Registry 





In Subsection 4.6.3, you must choose one of two procedures, depending on whether you 
are creating a new network of nodes running SR10 or updating an existing network from 
SR9 to SR10. 

The procedures in Subsections 4.6.5 and 4.6.8 might not be necessary at your site. All 
other procedures in this section are essential to successful operation of the registry. 

If you are creating a Domain internet, you should see Managing Domain Routing and 
Domain/OS in an Internet for more information. 

4.6.1 Planning a Configuration 

Use the following considerations to plan a configuration of registry servers for your site: 

o You can run more than one rgyd on a network. In an internet, we recommend 
that you run at least one rgyd in every network. 

• Nodes that run rgyd should have local disks. They also should have at least 3 MB 
of physical memory, more for very large registries. 

• Nodes that run rgyd should be running and available all the time. It is especially 
important that the node where the master server runs be available throughout the 
network or internet. 

Choose a site for the master server. If you decide to run several servers, choose sites for 
the slave servers. 

4.6-2 Starting Location Brokers 

Before you run registry servers, you must establish Location Brokers on your network. At 
least one Global Location Broker (glbd) must run on your network. In an internet, at least 
one glbd must run on each network of the internet. A Local Location Broker (llbd) must 
run on every node that runs a glbd and on every node that will run a registry server 
(master or slave). 

Managing the NCS Location Broker gives procedures for starting up Location Brokers. 

Refer to this manual now and then continue with Subsection 4.6.3. 

4.6.3 Creating the Registry Database 

There are two ways to create an SR10 registry database. 

Updating an SR9 Registry to SR10 

If you are updating from SR9 to SR10 system software on your network or internet, you 
should convert your SR9 registry database to SR10 format via the cvtrgy utility. Skip the 
rest of this subsection, follow the conversion procedures described in Making the Transi- 
tion, then proceed with Subsection 4.6.4. 
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Setting Up a New SR10 Registry 

If you are setting up a new network or internet of Domain nodes and SR10 Domain/OS is 
the only system software any of these nodes have ever run, you use the rgy_create utility 
to create a new database and initialize it with reserved names and accounts. You typically 
create the SR10 registry as part of your first SR10 installation. Since it is used only once, 
rgy_create resides in the /install/tools directory and is not included in subsequent SR10 
installations. See Installing Software with Apollo* s Release and Installation Tools for more 
information about rgy_create. 

4.6.4 Starting the Master Registry Server 

Log in on the master registry site node and use /bin/ps or /com/pst to verify that an llbd 
is running on the node. 

To start the master server, complete the following steps: 

1. Become root and enter the following command on the master node: 

c 

* /etc/server -p /etc/rgyd & 

The -p option causes /etc/server to create a process that runs under the SID that 
invoked the command, rather than the default of user. server. none. 

2. Create the file /etc/daemons/rgyd on that node, so that the server will start each 
time the system boots. Use the UNIX touch command or the Aegis erf command: 

$ touch /etc/daemons/rgyd (UNIX environments) 

$ erf /etc/daemons/rgyd (Aegis) 

4.6.5 Establishing Uniform UNIX Numbers 

If your Apollo systems share files with other UNIX systems, you should ensure that names, 
UNIX IDs, and account information are consistent between the Domain/OS registry and 
the foreign passwd and group files. For the purposes of this discussion, “file sharing” can 
take the form of direct access through facilities such as Domain NFS or indirect file trans- 
fer via media such as tar tapes. 

We provide a tool called import_passwd that helps you to identify and resolve conflicts of 
names, UNIX IDs and account information. If you plan to share files between Apollo 
systems and other UNIX systems, we recommend that you run import_passwd now to 
minimize the number of changes you have to make. Typically, you run import_passwd in 
a mode that changes IDs in the Apollo registry to match the IDs on the foreign systems; 
afterward, you will have to run another tool called syncids to ensure that the IDs stored in 
Apollo file systems match those stored in the registry. 

See Section 4.11 for detailed information about import_passwd. 

4.6.6 Setting Policies, Properties, and Passwords 

Before you make any further changes to the registry database, you should use the prop 
command in edrgy to view policies and properties and change them as desired. 
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We provide default passwords for all reserved accounts except user. none. none, which by 
default has no password. These defaults are set either by cvtrgy (if you converted from an 
SR9 registry) or by rgy_create (if you created a new SR10 registry). You should use edrgy 
to change or set the passwords for these accounts. 

Now is also the best time to change the owners of reserved registry data, if you do not 
want to use the defaults. See Subsection 4.2.7 for details. 

4.6.7 Adding Names and Accounts 

Your registry now contains the following names and accounts: 

• Those added as reserved information by rgy_create or cvtrgy 

• If you used cvtrgy, those derived from your SR9 registry 

• If you used import_passwd, those derived from the password and group files on 
your other UNIX systems 



Use edrgy to add any other names and accounts that your site requires. You can do this 
now or at any time later. 



4.6.8 Creating Slave Registry Replicas 



Follow the procedures in this subsection if you want to replicate the registry database. 



1. Log in on a slave node and use /bin/ps or /com/pst to verify that an llbd is run- 
ning on the node. 



2. To start the slave server, become root and enter the following command on the 
slave node: 

$ /etc/server -p /etc/rgyd -create & 



This command locates the master server, adds the local node to the master replica 
list, and causes the master to initialize a new database at the local node. 



3. As you did on the master node, create the file /etc/daemons/rgyd, so that the 
server will start each time the system boots. Use touch or erf: 

$ touch /etc/daemons/rgyd (UNIX environments) 

$ erf /etc/daemons/rgyd (Aegis) 

4. Repeat the above steps for each replica you want to create. 

You can use the lrep -state command in the rgy_admin tool to verify that the 
master and slave servers are running. 
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4.6.9 Restarting Registry Servers 



To restart a registry server, whether a master or a slave, run rgyd without any options: 
$ /etc/server -p /etc/rgyd& 



4.7 Managing the Registry 



Managing the registry requires you to administer both the information in the registry data- 
base and the operation of the registry server. You use rgy_admin to administer the opera- 
tion of the registry server and edrgy to edit data in the registry database. 

4.7.1 Managing the Registry Server 

The rgy_admin tool manages the operation and replication of the registry server. You can 
use rgy_admin to read and edit replica lists, delete replica registries, and stop registry 
servers. 

When invoked, rgy_admin issues a prompt, rgy__admin:, and enters an interactive mode, 
waiting for your input. Sections 4.8, 4.9 and 4.10 contain procedures for some tasks you 
might need to perform with rgy_admin. 

4.7.2 Editing the Network Registry Database 

The edrgy command manages the name and account information in the registry database. 
Using edrgy, you can add, edit, or delete any of the following information: 

• Information about persons, groups, and organizations 

• Group and organization membership lists 

• Policies for organizations and for the registry as a whole 

• Properties of the registry 

• Account information 

• Owner information 



You can also use edrgy to view registry database information without making changes. 



4.7.3 Editing the Local Registry Database 

You can use the -1 option of edrgy to edit a node’s local registry information. This form 
of the command is available to ordinary users and not reserved to the registry owner. 
Remember, however, that at each login, the operating system updates any entry in the 
local registry for the account used. 
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4.7.4 Merging Disjoint Registries 



Network reconfigurations sometimes require you to merge the databases of two registries 
that have been operating independently. 

We provide the rgy_merge tool to help you merge registry databases. This tool compares 
two master registry databases and informs you if any names or numbers conflict. You must 
use edrgy to resolve any conflicts before rgy_merge will actually perform the merge. 

There are two types of reconfigurations that require merging of registries: 

© Connecting two networks to create an internet 
® Combining two networks into one larger network 



Note that in this context, a “network” can consist either of several nodes or of a single 
standalone node running a network registry. 

If you are creating a Domain internet, see Managing Domain Routing and Domain/OS in 
an Internet. This book describes all aspects of creating an internet and includes procedures 
to merge registries. 

If you are combining two networks into one larger network, the procedures for merging 
registries in Managing Domain Routing and Domain/OS in an Internet still apply. You 
should perform the merge during off hours with as few users on the networks as possible. 
Until the merge is complete, two disjoint registries will exist on one network, so the 
chances of obtaining incorrect information in a registry lookup are greater than in the 
internet case. 

Section 4.9 contains several procedures for dealing with network reconfigurations. 



4.8 Routine Maintenance Procedures 

This section contains procedures for routine maintenance of the registry. 
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4,8.1 Backing Up the Registry Database 



Because the registry server maintains its most current data in memory and saves data to 
disk only periodically, we provide a special procedure for backing up the database. You 
should follow Procedure 4-1 either when you back up the disk containing the master 
replica of the database or when you back up the database only. The server will not accept 
updates while the backup is in progress. 



Procedure 4-1. Backing Up the Registry Database 

You must be an owner of the registry to perform Tasks 1 and 3 of this procedure. 

Task 1: Put the master server in maintenance state 

Use the state command in rgy_admin to put the master server in maintenance state. 
While in maintenance state, the server will refuse updates. 

Task 2: Back up the master replica 

Back up the master replica of the registry database by backing up either the entire 
volume or the /sys/registry tree. 

Task 3: Take the master server out of maintenace state 

Use the state command in rgy_admin to take the master server out of maintenance 
state. The server will resume accepting updates. 



4-18 Creating and Maintaining the Registry 






4.8.2 Checking Consistency of Registry Replicas 

You can use Procedure 4-2 to check that all replicas of the registry are operating and that 
all copies of the database are up to date. 

Procedure 4-2. Checking Consistency of Registry Replicas 

Task 1: Invoke rgy_admin 

Task 2: Use the lrep -state command 

The lrep -state command reads the replica list at the rgy_admin default host, queries 
each replica in the list, and displays information about the each replica that responds. 
The output of lrep -state shows which server is the master, the state of each server, 
and the time stamp of the most recent update at each replica of the database. 

In the following example, rgy__admin queries the slave registry server at //tosca, which 
provides information about the master replica at //aida and about slave replicas at 
//tosca and //lulu. All replicas are operating normally (“in service”) and both slaves 
are in synch with the master. 

$ rgy_admin 

Default object: rgy default host: dds: //tosca 
State: in service slave 
rgy_admin: lrep -state 

dds://tosca state: in service 1988/04/25.10:49:23 

dds://lulu state: in service 1988/04/25.10:49:23 

(master) dds: //aida state: in service 1988/04/25.10:49:23 

The online and printed reference documentation for rgy_admin lists and describes 
other states that lrep may report. 



Creating and Maintaining the Registry 4-19 






4.8.3 Restarting Registry Servers 



If you created the file /etc/daemons/rgyd at every registry site, as described in Subsection 
4.6.8, a registry server should automatically restart whenever the node boots. In the event 
that a server fails to restart or dies, you can use Procedure 4-3 to restart it by hand. This 
procedure applies to either master or slave servers. 



Procedure 4-3. Restarting a Registry Server 

Task 1: Become root 

Become root on the node where you want to restart the server. Issue the following 
shell command: 

$ /etc/server -p /etc/rgyd & 

Task 2: Verify that the server is running 

Use the lrep -state command in rgy_admin, as described in Procedure 4-2, to verify 
that the server is now running. If it is not, see the troubleshooting procedures in Sec- 
tion 4.10. 

Task 3: Verify that /etc/daemons/rgyd exists 

Check that the file /etc/daemons/rgyd exists so that the server will automatically re- 
start when the system boots. 
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4.9 Reconfiguration Procedures 



This section describes procedures to help you deal with hardware and network reconfigura- 
tions. 

4.9.1 Changing the Network Address of a Registry Site 

If you reconfigure a network or relocate a node that runs a registry server, the network 
address of a registry site may change. Since registry replicas use their network addresses to 
locate and identify each other, it is crucial that every replica learn of any changes to 
network addresses. 

If the network address of a registry site has changed, you must stop the registry server at 
that site (via the stop command in rgy__admin) and then restart the server (as described 
in Procedure 4-3). The registry server automatically learns its new network address when it 
restarts. 

Changes of network addresses can be propagated to registry replicas in three ways: 

® If only the master replica changes its network address, and all slaves retain their 
addresses, the master will automatically propagate its new address to all slaves. 

• If the master replica does not change its network address, but one or more slaves 
do, each slave will locate the master and give the master its new address. The 
master will then propagate the new address to all other slaves. 

® If the master replica and one or more slaves change their network addresses, 

there will be no way for the master and the changed slaves to contact each other, 
and you should execute Procedure 4-4 to update the replica list at the master. 
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Procedure 4-4. Updating the Replica List at the Master Registry 

You must be an owner of the registry in order to perform Task 3 of this procedure. 

Task 1: Set the default host to the master registry site 

Invoke rgy_admin. Set the default host to the master registry site by issuing the 
set -m command. 

Task 2: List the addresses of all registry replicas 

Use the lrep -na command in rgy_admin to list the network addresses of all registry 
replicas (as stored in the replica list at the master site). 

Task 3: Update the replica addresses 

For any slaves whose network addresses have changed, use the reprep command in 
rgy_admin to update these addresses. Use lrep -na again to verify that the replica list 
at the master site is now correct. 

Once the replica list at the master site is updated, the master server will propagate 
changes of network address to the slave servers as necessary. 



4.9.2 Changing the Master Registry Site 

Smooth operation of the registry requires that the node running the master registry server 
always be available. If you are planning to remove this node from your network or to shut 
it down for an extended period, you should change the master registry site. 

Procedure 4-5 describes a clean, graceful method for changing the master registry site by 
causing the master site and a slave site to reverse roles. It assumes that the registry servers 
at these two sites are operating normally. After the original master has been changed to a 
slave, you can use Procedure 4-6 to delete it. 

Section 4.10 contains procedures for dealing with abnormal situations arising, for instance, 
from hardware or network failure. 
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Procedure 4-5. Changing the Master Registry Site 

You must be an owner of the registry in order to perform Task 3 of this procedure. 

Task 1: Choose the master registry site 

Choose the new master site. A slave replica must exist at this site. If necessary, create 
the slave replica, as described in Subsection 4.6.8. 

Task 2: Set the default host to the master registry site 

Invoke rgy_admin. Set the default host to the current master registry site by issuing 
the set -m command. 

Task 3: Change the master registry site 

Change the master site by issuing the following command: 

rgy_admin: change__master -to //newmaster 

where / /newmaster is the new master site you chose in Task 1. 

Task 4: Verify that the master site has been changed 

Use lrep -state to verify that the master site has been changed. 

The former master site is now a slave site. You can delete this slave replica by execut- 
ing Procedure 4-6. 
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4,9.3 Deleting a Slave Registry Replica 



If you are planning to remove a slave site node from your network or to shut it down for 
an extended period, you should delete the registry replica at that site by following Proce- 
dure 4-6. 



Procedure 4-6. Deleting a Slave Registry Replica 

You must be an owner of the registry in order to perform Task 2 of this procedure. 

Task 1: Set the host to the current master registry site 

Invoke rgy_admin. Set the default host to the current master registry site by issuing 
the set -m command. 

Task 2: Delete the slave replica 

Delete the slave replica by issuing the following rgy_admin command: 

rgy_admin: delrep II slave 

where II slave is the site of the slave replica to be deleted. The master server will in- 
struct the slave replica to delete itself. 

Task 3: Verify that the slave has been deleted 

Use lrep -state to verify that the slave replica has been deleted. The deletion may 
take a while. Until the slave is actually deleted, lrep -state will show the slave as 
marked for deletion. 
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4.10 Troubleshooting Procedures 

This section contains procedures for troubleshooting the registry. You should not need to 
use any of these procedures except when network or hardware failures have disrupted 
operation of the registry. 

4.10.1 Recreating a Slave Registry Replica 

If a slave replica of the registry database has become corrupted or irrecoverably out of 
date, you can use Procedure 4-7 to recreate the replica. 



Procedure 4-7. Restoring a Slave Database and Restarting Its Server 

Task 1: Become root 

Become root on the node where you want to recreate the slave replica. Use the 
UNIX ps command or the Aegis pst command to check whether a rgyd is running. 
If there is one, stop it via the stop command in rgy_admin. (You must be an owner 
of the registry in order to use the stop command.) 

Task 2: Recreate the slave replica 

Recreate the slave replica by issuing the following shell command: 

$ /etc/server -p /etc/rgyd -recreate & 

This destroys the existing database, creates a new one, and starts a slave server. 

Task 3: Verify that /etc/daemons/rgyd exists 

Check that the file /etc/daemons/rgyd exists, so that the server will automatically re- 
start when the system boots. 
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4.10.2 Recovering from Loss of the Master Registry Replica 

If the master registry replica becomes inoperable or unavailable for an extended time, you 
may need to replace it or restore it. This subsection contains several procedures for recov- 
ery of the master replica. You should read through all of them and select the one most 
appropriate for your particular situation. 

If there exists a slave replica with a nearly current database, you can use Procedure 4-8 to 
turn this replica into the master. (You can check the time stamps of slave databases via 
the lrep -state command in rgy_admin.) If no such slave exists, you can use Procedure 
4-10 or Procedure 4-11 to restore the registry database from a backup tape. 



Procedure 4-8. Turning a Slave into a Master 

You must be an owner of the registry in order to perform Task 2 of this procedure. 

Task 1: Choose the slave replica 

Choose the slave replica that will become the new master. 

Task 2: Make the chosen slave the master registry site 

Invoke rgy_admin. Issue the following rgy__admin commands to set the chosen slave 
site as the default host and to turn this slave into a master: 

rgy__admin: set -h Unewmaster 
rgy_admin: become -master 

where Unewmaster is the site of the slave replica you chose in Task 1. 

Task 3: Verify the new master site 

Use lrep -state to verify that Unewmaster is now the master registry site. 

If the old master replica becomes available again, you must immediately change either 
the old master or Unewmaster to a slave replica, to prevent inconsistencies in the da- 
tabase replicas. Retain the master with the more current database and use Procedure 
4-9 to turn the other master into a slave. 



4-26 



Creating and Maintaining the Registry 





Procedure 4-9. Turning a Master into a Slave 



Task 1: 



Task 2: 



Task 3: 



Use this procedure to turn a master replica into a slave. You should use this proce- 
dure only if you have more than one master running on your network or internet, a 
highly unusual condition. (If you are performing a merge of two disjoint registries, two 
masters will coexist temporarily, but rgyjmerge will turn one of them into a slave.) 

You must be an owner of the registry in order to perform Task 2 of this procedure. 



Choose the master replica 

Choose the master replica that will become a slave. 



Make the master into a slave replica 

Invoke rgy_admin. Issue the following rgy_admin commands to set the chosen mas* 
ter site as the default host and to turn this master into a slave: 

rgy_admin: set -h I /newslave 
rgy_admin: become -slave 

where //newslave is the site of the master replica you chose in Task 1. 



Verify that the master is a slave 

Use lrep -state to verify that / /newslave is now a slave registry site. 
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Procedure 4-10. Restoring a Master Server at Its Original Site 



Use this procedure to restore a master replica at its original location. See Procedure 
4-11 if you are restoring the database at a different location. 

Task 1: Become root and stop rgyd 

Become root on the master site node. Use the UNIX ps command or the Aegis pst 
command to check whether a rgyd is running. If there is one, stop it via the stop 
command in rgy_admin. (You must be an owner of the registry in order to use the 
stop command.) 

Task 2: Restore /sys/registry 

Restore the /sys/registry tree from the backup media. 

Task 3: Restart rgyd 

Restart the server by invoking rgyd without any options: 

$ /etc/server -p /etc/rgyd & 

Task 4: Verify that /etc/daemons/rgyd exists 

Check that the file /etc/daemons/rgyd exists, so that the server will automatically re- 
start when the system boots. 
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Procedure 4-11. Restoring a Master Server at a New Site 



Task 1: 



Task 2: 



Task 3: 



Task 4: 



Task 5: 



Use this procedure to restore a master replica at a new location. You must be an 
owner of the registry in order to perform Task 4 of this procedure. 



Become root and stop rgyd 

Become root on the new master site node. Use the UNIX ps command or the Aegis 
pst command to check whether a rgyd is running at the new site. If there is one, stop 
it via the stop command in rgy_admin. (You must be an owner of the registry in or- 
der to use the stop command.) 



Restore /sys/registry 

Restore the /sys/registry tree from the backup media. (Alternatively, if the disk that 
contained the master replica on the original site is still intact, you can move the disk 
to the new node; in this case, you must run the chuvol utility on the volume you are 
moving.) 



Restart rgyd 

Restart the server by invoking rgyd with the -restore_master option: 

$ /etc/server -p /etc/rgyd -restore_master & 

Delete the old master site 

Use the delrep -force command in rgy_admin to delete the old master site from the 
replica list, as described in Procedure 4-12. 

Create /etc/daemons/rgyd 

Create the file /etc/daemons/rgyd at the new site, so that the server will automatically 
restart when the system boots. 
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4.10.3 Forcibly Deleting a Registry Replica 



Use Procedure 4-12 to delete a registry replica when the ordinary method described in 
Procedure 4-6 has failed. 

Procedure 4-12 uses the drastic delrep -force command in rgy_admin to delete the 
registry replica from the replica lists at all other registry sites. It does not actually stop the 
server or delete its database and, indeed, does not communicate at all with the server. You 
should apply this method only if the replica has died irrevocably. 

If you have forcibly deleted a replica and the replica later resumes operation, you should 
use the reset command in rgy_admin to stop the server and delete its database, since the 
forced deletion has made all other registry replicas unaware of its existence. 



Procedure 4-12. Forcibly Deleting a Registry Replica 

You must be an owner of the registry in order to perform Task 2 of this procedure. 

Task 1: Set the default host to the current master site 

Invoke rgy_admin. Set the default host to the current master registry site by issuing 
the set -m command. 

Task 2: Delete the replica 

Delete the replica by issuing the following rgy_admin command: 

rgy_admin: delrep l/regsite -force 

where / / regsite is the site of the replica to be deleted. 
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4.11 The import_passwd Command 



The import__passwd command creates entries in the Apollo registry based on information 
in UNIX password and group files. It provides a method of ensuring consistency between 
the Apollo registry and the UNIX password and group entries. Consistency is crucial for 
most forms of file sharing between Apollo systems and other UNIX systems. 

Use this command when you are 

• Attaching Apollo node(s) to a foreign network 

• Attaching foreign node(s) to an Apollo network 

• Connecting Apollo and foreign networks 

4.11.1 How import_passwd Processes 

When import_passwd processes, it compares the foreign group and password file entries to 
the Apollo registry entries. It can find two types of conflicts: 

• Name Conflicts. These conflicts arise when the same name string is defined in 
the Apollo registry and the foreign system. “Joe 102” and “Joe 555” are an ex- 
ample of such a conflict. The duplicate name may represent the same user or two 
different users. 

® UNIX ID Conflicts. These conflicts arise when the same UNIX ID is defined in 
the Apollo registry and the foreign system for users with different names. “Joe 
102” and “Ann 102” are an example of such a conflict. 

These conflicts can be found separately, as in the examples above, or together. For in- 
stance, an Apollo entry of “Joe 102” and a foreign entry of “Joe 102” are in conflict. 
Unless they represent the same user, one of the entries must be changed. 

As import jpasswd processes, it performs the following steps in sequence: 

1. It puts the Apollo registry in maintenance mode and reads the foreign group and 
password files. 

2. It compares the foreign group file entries to the Apollo group entries. If there are 
no conflicts, it creates Apollo group registry entries corresponding to the foreign 
groups. (Section 4.11.3 describes what happens if there are conflicts.) Note that 
the members of the groups are not added at this time, but in Step 4. 

3. It compares the entries in the foreign password file to the Apollo person and ac- 
count entries. Again, if there are no conflicts, it creates Apollo person and ac- 
count entries corresponding to the foreign file. 

4. If there are members in the foreign groups handled in Step 2, it adds them to the 
appropriate group in the Apollo registry. 

5. It then prompts for whether or not to make the changes. If you specify that the 
changes should be made, it saves the changes to the registry. 
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4.11.2 Other Entries Created by import_passwd 



The import_passwd tool modifies only person names, person IDs, group names, group 
IDs, group members, and account passwords. It does not modify any of the additional 
information in the registry. 

For example, assume you have a foreign password entry for user jack and group staff and 
an Apollo account entry of jack.staff.none. You run import_passwd with the -i option. 
This option tells import_passwd to consider the entries identical. The home directory 
specified in the foreign network is /usr/u/jack; the home directory specified in the Apollo 
network is //gimli/jack. The import__passwd tool will not change the Apollo registry to 
match the foreign home directory. The jack.staff.none entry in the Apollo registry will 
have a home directory of //gimli/jack, not /usr/u/jack. 

If jack.staff.none did not exist in the Apollo registry, import jpasswd would create a new 
registry entry. For the additional information, it assigns the following values: 

For Person and Group Entries: 

• fullname = ” (that is, empty). 

• owner = Same as the owner of the domain as listed in the registry properties (that 
is, the owner for new person entries is set to Person Owner, and the owner for 
new group entries is set to Group Owner.) 

• alias/primary = Primary for first entry; alias for subsequent ones. 

• projlist_ok (for groups only) = Yes. 

• passwd = For groups only, taken from the foreign group file. 

• membership list = For new groups only, all persons listed in the foreign group file 
and all persons with accounts in the foreign password file with that group. 

For Account Entries: 

• abbreviation = Shortest possible abbreviation that does not conflict with pre-exist- 
ing Apollo accounts. 

• account_valid = True. 

© gecos = Same as foreign password file. 

• homedir = Same as foreign password file. 

• shell = Same as foreign password file. 

• passwd = Same as foreign password file. Note that you must modify or reset im- 
ported passwords before user authentication is possible and for the account to be 
usable in a pre-SRIO registry. 

• passwd_dtm = Date and time import_passwd was run. 

• passwd_valid = True. 
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4.11.3 Resolving Conflicts 



When you use import_passwd, you must decide how to resolve the conflicts it will en- 
counter. The import_passwd command provides a number of options to help you. If the 
conflict cannot be resolved even with the option instructions, importjpasswd will prompt 
you for resolution. The options are described in the following subsections. 



The Identical User Option 

The -i option lets you specify that duplicate names are not in conflict but, instead, repre- 
sent the same identity. When import_passwd finds duplicate name entries, it processes 
them as though they are the same user. If you do not use the -i option, import_passwd 
will prompt you to resolve the name conflict. 

The Favored Entry Option 

The -a (favor Apollo) and -f (favor foreign) options let you specify whether the Apollo or 
the foreign entry is the favored entry. A favored entry is retained as is. You are prompted 
to modify non-fa vored entries. 

For example, suppose you run import_passwd with the -a (favor Apollo) option and 
without the -i (identical user) option. During processing, the program encounters an 
Apollo entry of joe 555 and a foreign entry of joe 102. Because the Apollo entry is fa- 
vored, joe 555 will be retained in the Apollo registry, and you will be prompted for a new 
UNIX ID (a new name) for joe 102. 

The import_passwd command also uses the favored entry to resolve UNIX ID conflicts. 
For example, suppose you are running import_passwd with the options described above. 
During processing, it encounters an Apollo entry of joe 555 and a foreign entry of ann 
555. Because the Apollo entry is favored, import_passwd prompts you for a new UNIX 
ID for “ann.” 

Be aware, however, that Apollo reserved entries cannot be modified. (Table 4-2 list the 
Apollo reserved entries.) The import_passwd command will not modify a reserved entry 
even if it is the non-favored entry. For example, suppose you are running importjpasswd 
with the foreign entry as the favored entry. During processing, it encounters a foreign 
group entry of misc 0 and an Apollo group entry of wheel 0. Because group wheel 0 is a 
reserved Apollo entry, you will be be prompted to modify the foreign entry, even though it 
is the favored entry. 
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Conflict Summary 

Table 4-3 summarizes the effects of the identical user and favored entry options. 

Table 4-3. Effects of Identical User and Favored Entry Options 



Options 

Used 


Foreign 

Entry 


Apollo 

Entry 


Result in 
Apollo Registry 


Comments 


-i, -a 


joe 102 


joe 555 


joe 555 


Name collision. Retain Apollo entry. 




joe 102 


ann 102 


ann 102 


UNIX ID conflict. Request new 
UNIX ID for joe. 


-i, -f 


joe 102 


joe 555 


joe 102 


Name collision. If 102 already exists 
in Apollo, prompt for new UNIX ID 
for that Apollo entry. 




joe 102 


ann 102 


joe 102 


UNIX ID conflict. Request new 
UNIX ID for ann. 


-a 


joe 102 


joe 555 


joe 555 


Name conflict. Request new name for 
joe 102, and if 102 is already defined 
in Apollo, a new UNIX ID as well. 




joe 102 


ann 102 


ann 102 


UNIX ID conflict. Request new UNIX 
ID for joe. 


-f 


joe 102 


joe 555 


joe 102 


Name conflict. Request new name for 
joe 555, and if 102 is already defined 
in Apollo, prompt for a new UNIX ID 
for that Apollo entry. 




joe 102 


ann 102 


joe 102 


UNIX ID conflict. Request new UNIX 
ID for ann. 
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4.11.4 The import_passwd Syntax 

This section presents the importjpasswd command and describes the command arguments 
and options. 



import_passwd [-i] [-a | -f] [-c] [-o org] -s pathname [-v] 



1 


Identical name strings are not in conflict, but represent the same 
identity. 


-a (D) 


Favor Apollo entries. 


-f 


Favor foreign entries. 


-c 


Run in check mode: process the command showing conflicts, but 
make no changes to the files. 


“O org 


org is the name of the Apollo organization to be used for all imported 
account entries. The default is the organization named “none.” 


-s pathname 


pathname is the path to the directory containing the foreign password 
and group files to be imported. 


-v 


Run in verbose mode: generate a verbose transcript of all activity. 



4.11.5 Using import_passwd 

This section describes conflicts you may encounter when running importjpassword. 

Using Check Mode 

You should first run importjpasswd in check mode using the -c option. In this mode, 
importjpasswd simulates the results of a processing run showing the conflicts that will be 
be encountered when importjpasswd is run without the -c option. 

Check mode gives you a good idea of the quantity and complexity of the potential con- 
flicts. However, check mode does not make any changes to the file. When you run without 
the -c option and make changes to resolve conflicts, these changes can in turn create 
further conflicts not readily apparent in check mode. 

If you encounter numerous conflicts in check mode, you may find it more efficient to 
manually edit either the registry or the UNIX group and password files to resolve some 
obvious conflicts before you run import jjasswd. 
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Answering Prompts 

When you run import_passwd, you may be prompted for names and numbers (UNIX 
IDs). The following conventions apply to your answers to these prompts: 

• Names must 

Begin with a lowercase letter 

- Contain only lowercase letters, digits, or underscore characters 

- Not exceed 32 characters in length, unless your system imposes UNIX restric- 
tions, in which case, they cannot exceed 8 characters in length 

If your system imposes UNIX name restrictions, you should carefully evaluate the 
effect of these restrictions on existing entries in the files against which you are 
running import_passwd. Some of the entries may be longer that 8 characters. 

• Numbers must range between 0 and 65535, inclusive. (We suggest that you not 
use numbers under 100, since these may be reserved in future releases.) 

If you enter a name or number in an incorrect format, import_passwd will ignore your 
entry and re-prompt. 

Processing Prerequisites 

The Apollo registry must exist before you can use import_passwd. If you are simply 
adding a few Apollo nodes to a foreign network, you can create a new, but empty, registry 
to meet this requirement. Once the registry exists, the registry server must be running and 
you must be logged on as root. 

Synchronizing Apollo UNIX IDs 

If importjpasswd makes any changes to Apollo UNIX IDs, you must run the /etc/syncids 
tool on every Apollo node in your network. This tool ensures that the changes are syn- 
chronized with the UNIX IDs stored on disk. On nodes that have more than one disk 
volume, you must run syncids on each volume. 

If your Apollo registry is replicated before you run syncids, you should use the 
lrep -state command in the /etc/rgy_admin tool to verify that all slave registry servers are 
up to date. This command shows the time stamps of the most recent changes to each 
replica of the registry database. You should not run syncids until the time stamps for all 
slave servers match the time stamp for the master. 

See the reference documentation for syncids and rgy_admin online or in the Command 
Reference manual for your environment. 
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Synchronizing Foreign UNIX IDs 



If any of the conflicts found by import_passwd involve reserved information in the Apollo 
registry, you may have to resolve conflicts by changing names and IDs on your foreign 
systems. You also may have to change names and IDs on your foreign systems if you run 
import_passwd with the -a (favor Apollo) option. In that event, you must then use the 
chown and chgrp utility to update the UNIX IDs on all affected files and directories in the 
foreign file systems. 



4.12 A Sample importpasswd Session 

This subsection illustrates a simplified import_passwd session. The session uses the foreign 
group file and password files shown in Figure 4-3 and the Apollo group file and password 
entries shown in Figure 4-4. 



Foreign Group File Entries 



root::0:root 
other: : 1: 

bin : : 2 : r oot , bin , daemon 

sy s : : 3 : r o ot , bin , sy s , a dm 

adm: : 4 :root , adm , daemon 

mail::6:root 

rje::8:rje,shqer 

daemon : : 1 2 : root, daemon 

tgroup::35: 

Foreign Password File Entries 

root: :0:1:0000-Admin (0000):/: 
daemon:: l:l:0000-Admin(0000):/: 
bin::2:2:0000-Admin(0000):/bin: 
sys::3:3:0000-Admin(0000):/usr/src: 
adm::4:4:0000-Admin(0000):/usr/adm: 
uucp : : 5 : 5 : 0 0 0 0 -uucp (0000): /usr/lib/uucp : 

nuucp:: 10: 10:0000-uucp(0000) :/usr/spool/uucppublic: /usr/lib/uucp/ 
uucico 

rje::18:18:0000-rje(0000):/usr/rje: 
trouble: :70: 1 trouble (0000) :/usr/lib/trouble: 
lp::71:2:0000-lp(0000):/usr/spool/lp: 

setup: :0:0:general system administration:/usr/admin:/bin/rsh 
powerdown: :0:0 .’general system administration:/usr/admin:/bin/rsh 
sysadm::0:0:general system administration :/usr/admin:/bin/rsh 
checkfsys::0:0:check diskette file system:/usr/admin:/bin/rsh 
makefsys::0:0:make diskette file system:/usr/admin:/bin/rsh 
mountfsys::0:0:mount diskette file system :/usr/admin:/bin/rsh 
umountfsys::0:0:unmount diskette file system :/usr /admin :/bin/rsh 



Figure 4-3. Foreign Group and Password Entries 



Creating and Maintaining the Registry 4-37 









Group Entries 



wheel: :0: 
daemon:: 1: 
none:: 2: 
backup:: 3 :user 
locksmith: :4: 
login: :5: 
mail::6:bin 
bin::7:root 
server: :8: 
sys::9:root 
staff:: 10: 

sys_admin: : 1 1 :user 

s ys_j> ro j::12: 

tgroup::35: 



Password Entries 



root:sqlRclUrrblL6:0:10::/: 

daemon:sqlRclUrrblL6:l:2::/: 

none:sqlRclUrrblL6:2:2::/: 

user:sqlRclUrrblL6:3:2::/: 

lp:sqlRclUrrblL6:4:7::/: 

sy s_person : sq 1 RclU rrb 1 L 6 : 5 : 2 : : / : 

admin:sqlRclUrrblL6:6:2::/: 

uucp : sq 1 RclUrrb 1L6 : 7 : 2 : :/usr/spool/uucppublic : 

bin:sqlRclUrrblL6:8:7::/: 



Figure 4-4. Apollo Group and Password Entries 

The following subsections describe a session in which you perform the following tasks: 
invokethe command, examine the group entries, examine the password file, add members 
to groups, and update the registry. 

Phase 1: Invoking import__passwd 

1. In the sample session, the following form of the import_passwd command is en- 
tered at the shell prompt: 

$ importjpasswd -s sys5.3_tapes/adm -i -v 

This command specifies the following: 

• Identical names represent the same identify (-i) 

• The pathname of the foreign file (-s sys5.3_ tapes/adm) 

• Apollo entries should be favored (default of -a) 

• Not running in check mode (-c not specified) 

• Do run in verbose mode (-v) 
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2. The system puts the registry in maintenance mode, reads the foreign group and 
password files, and begins to create Apollo group entries in the Apollo registry: 

Preparing registry. . . 

Preparing foreign files... 

Creating Group entries from foreign group file... 

Phase 2: Examining the Group Entries 

If you examine Tables 4-2 and 4-3, you can see that the name root in the foreign and 
the name wheel in Apollo both have UNIX IDs of 0. 

3. The importjpasswd command tells you this and, since Apollo entries are favored, 
prompts for a new UNIX ID for the foreign entry: 

root : : 0 : root 

? ( import_j?asswd) Group - UNIX id conflict 

Foreign Group: ’’root' 1 0 Apollo: "wheel” 0 (reserved). 

Please enter new UNIX id for Foreign Group 'root' 0: 100 <RETURN> 
» Adding pgo entry for: root 100 

The value 100 is entered as the new UNIX ID for the foreign group entry. Note 
that import_passwd displays the foreign entry as it examines it (in the sample 
above, root: :0:root). And, because it is running in verbose mode, im- 
portjpasswd describes the actions it is taking. Each such description is prefaced 
with the symbols ». 

If you were running import_passwd in check mode, you would not be prompted 
for a UNIX ID. Instead, you would be informed of the need and processing would 
continue. The message would look like 

root: :0:root 

? (import jpasswd) Group - UNIX id conflict 
Foreign Group: "root" 0 Apollo: "wheel" 0 (reserved), 
need new UNIX id for Foreign Group 

(UNIX id for Apollo "wheel" is currently 0) 

4. The import_passwd command then finds another UNIX ID conflict: 
other : : 1 : 

? (import_passwd) Group - UNIX id conflict 

Foreign Group: "other" 1 Apollo: "daemon" 1 (reserved). 

Please enter new UNIX id for Foreign Group ' other' 1: 101<RETURN> 
» Adding pgo entry for: other 101 

Note that import_passwd tells you that the UNIX ID of 1 is reserved in Apollo. 
Because 1 is reserved, even if you had run import_passwd with the foreign entry 
favored, you would still be prompted for a new entry for the foreign UNIX ID. 

The import_passwd command will not change reserved entries. 
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5. If import _passwd finds no conflicts, it displays the group entries as it processes 
them and, because it is running in verbose mode, the actions it is taking: 

bin: : 2 :root, bin, daemon 

» Foreign Group: "bin" 2 Apollo: "bin'* 7 (reserved) 

» -i specified - retaining Apollo UNIX id 

sys : : 3 : root , bin , sys , adm 

» Foreign Group: "sys" 3 Apollo: "sys" 9 (reserved) 

» -i specified - retaining Apollo UNIX id 

As it continues through the foreign group file, import_passwd finds two other 
UNIX ID conflicts: foreign entries adm 4 and rje 8 and Apollo entries locksmith 
4 and server 8, respectively. 

Phase 3: Examining the Password File 

6. Importjpasswd then proceeds to create Apollo person and account entries from 
the foreign password file. It displays: 

Creating Person entries and Accounts from foreign passwd file... 

7. The first two entries are processed with no conflicts: 

root: : 0:1: 0000-Admin (0000) :/ 

» Foreign Person: "root” 0 Apollo: '‘root" 0 (reserved) 

» -i specified and UNIX ids match - no change necessary 
» Adding account for root . other .none . 

daemon : : 1 : 1 : 0000-Admin ( 0000 ) : / 

» Foreign Person: "daemon" 1 Apollo: "daemon" 1 (reserved) 

» -i specified and UNIX ids match - no change necessary 
» Adding account for daemon. other .none. 

The import_passwd command displays the names of the registry accounts it is 
creating. If you had changed a person or group name to resolve a previous 
name conflict, the new name would be displayed. For example, suppose that 
you had a foreign and an Apollo entry of joe.other.none. During im- 
port_passwd processing, you changed the name of the Apollo joe to smith. 
When importjpasswd created the Apollo person and account entries, a ver- 
bose display would look like: 

joe : : 1 : 1 : 0000-Admin ( 0000 ) : / 

» Adding account for smith . other . none. 

The foreign entry is displayed first with its correct name, joe. The account 
being added to the Apollo registry is displayed by its new name, smith. Im- 
portjpasswd keeps track of changes that are made and the relationships that 
existed before the changes were made. 

8. The third entry produces the following warning message: 

bin: :2:2:0000-Admin(0000) :/bin 

» Foreign Person: "bin" 2 Apollo: "bin" 8 (reserved) 

» -i specified - retaining Apollo UNIX id 
» Adding account for bin. bin. none . 

(WARNING) "bin. bin. none" : Account already exists and is re- 
tained unchanged. 
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This message is notifying you that the bin. bin. none account exists in the Apollo 
registry. The Apollo account will retain its information (that is, abbreviation, ac- 
count_valid, gecos, passwd, shell, home directory, passwd__dtm, and passwd_valid) , 
even though the foreign account may have information that differs from the 
Apollo account. 

9. Processing continues. The import_passwd command discovers two more UNIX 
ID conflicts (foreign sys 3 and Apollo user 3; foreign adm 4 and Apollo lp 4). 
Then import_passwd finds an un-named group in the foreign password file and a 
UNIX ID conflict. 

First import_passwd prompts you for a group name: 

uucp : : 5 : 5 : OOOO-uucp (0000) : /usr/lib/uucp 
» Foreign Person: "uucp" 5 Apollo: "uucp" 7 (reserved) 

» -i specified - retaining Apollo UNIX id 
? (import_passwd) Foreign Group 5 is unnamed. 

(UNIX id also conflicts with Apollo ‘•login 11 (reserved) ) . 
Please enter a name for Foreign Group 5: group_105 <ENTER> 

In the sample session, group_105 is entered as the new name. 

Note that if you were running in check mode, import_passwd would supply a 
name for the group in order to keep processing. The prompt would look like: 

uucp : : 5 : 5 : OOOO-uucp (0000) : /usr/lib/uucp 

» Foreign Person: "uucp“ 5 Apollo: "uucp" 7 (reserved) 

» -i specified - retaining Apollo UNIX id 
? (import_passwd) Foreign Group 5 is unnamed. 

(UNIX id also conflicts with Apollo "login" (reserved) ) . 
Temporarily using the name of "group_5" 

Then, importpasswd asks you for the new UNIX ID for the group: 

? (import_passwd) Group - UNIX id conflict 

Foreign Group: "gl05" 5 Apollo: "login" 5 (reserved). 

Please enter new UNIX id for Foreign Group 'gl05' 5: 105 <ENTER> 
» Adding pgo entry for: gl05 105 
» Adding account for uucp . gl05 . none . 

Phase 4: Adding Members to Groups 

10. When import_passwd completes processing of the foreign password file, it adds 
the members to the groups: 

Adding memberships from foreign group file. . . 
root : : 0: root 
Member: root 
other: : 1: 

bin: : 2 : root , bin, daemon 
Member: root 
Member: bin 
Member : daemon 

As it adds the members, import_passwd displays them. If there are no members 
added (as in group other::!:), none are displayed. If you are not running in ver- 
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bose mode, only the names of the groups are displayed as they are processed, not 
the members being added. 

11. When import_passwd processes the rje::8:rje,shger entry, it displays the follow- 
ing message: 

rje: :8:rje, shqer 
Member : r j e 
Member : shqer 

? ( import_passwd) Cannot add member - Person is unknown or invalid 

In foreign UNIX systems, you can add members to groups even if the person has 
not been added as a person. In Apollo systems you cannot. The import_passwd 
command has found a member of a foreign group who has not been added as a 
person. Therefore, importjpasswd will not add that member to the group. 

Phase 5: Updating the Registry 

12. Processing continues until importjpasswd completes adding members to groups, it 
recaps the results of its processing: 

0 name conflicts, 8 UNIX id conflicts, 3 unnamed groups,l error, 

2 warnings. 

And then asks if you want to save the changes: 

Import operation successful. Update registry [y/n]? y <RETURN> 
In this sample session, the answer is Y (yes). 

13. The import_passwd command then saves the changes and completes processing: 

Closing registry. . . 

Closing foreign files... 

Done. 

Because the -i option was specified in the command used in the sample session, 
no name conflicts were encountered. A sample of the prompt resulting from a 
name conflict is shown below: 

bin: : 2 :root, bin, daemon 

? (import jPasswd) Group - Name conflict 

Foreign Group: "bin” 2 Apollo: "bin" 7 (reserved) 

Please enter new name for Foreign Group "bin”: fbin <ENTER> 

» Adding pgo entry for: fbin 2 

In the sample above, a new name of fbin is assigned in the Apollo registry to en- 
try representing the foreign group bin. 
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4.13 Local Registries 



Each node can have a local registry that contains information about the node’s most recent 
users and the date and time when they last logged in. If you log in to a node and no 
registry server is available on the network, the operating system checks the node’s local 
registry for information about your account. If the information exists in the local registry, 
the system allows you to log in with that account; if not, it refuses to log you in. If both 
the network registry and the local registry are unavailable, the system will always allow you 
to log in with the account name user. none. none. 

4.13.1 Setting Up the Local Registry 

The operating system creates a local registry the first time a user logs in to a node, pro- 
vided a registry server is running somewhere on the network. Thereafter, the local registry 
is updated every time someone logs in to the node. Users can edit some of the information 
in a node’s local registry by invoking the edrgy -1 command on that node. 

4.13.2 Running a Small Network without Registry Servers 

If you have a small network consisting of one or two nodes with no more than 10 ac- 
counts, it is possible to operate your network by using only local registries. You need to 
run rgyd while you create accounts, then copy account information into the local registry 
on each node, as follows: 

1. Start a rgyd process on one node and use edrgy to create the accounts you need. 

2. Use the copy command in edrgy to add account information to the local registry. 
The command copy %.%.% will fill the local registry to capacity. 

3. Use the stop command in rgy_admin to terminate the rgyd process. 

The accounts you created now have access to the nodes via the local registry. Of course, if 
you wish to change any account information, you must restart rgyd to make the changes. 

(Even without local registries, all reserved entries are available to the operating system, so 
users on your network can log in as user. none. none.) 

□□ 
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Protection of Files and Directories 
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This chapter describes how SR10 Domain/OS controls access to files and directories. 
Domain/OS implements the UNIX protection model and extends it with an Access Control 
List (ACL) model. Under Domain/OS, UNIX protection operates as you would expect on 
other UNIX systems, while the ACL mechanism provides greater flexibility in controlling 
access to objects. 

Section 5.1 describes UNIX protection. Section 5.2 describes the ACL model and the ways 
in which it extends the UNIX model. Section 5.3 explains how Domain/OS derives UNIX 
modes from ACLs. (If you use only vanilla UNIX protection, without any of the ACL 
extensions, you can skip Sections 5.2 and 5.3.) The remaining sections discuss protection 
in the context of system administration. 

NOTE: The SR10 protection-checking mechanism can operate over the 

network with the mechanism released at SR9.7, but not with those 
released prior to SR9.7. Therefore, if your site is upgrading to 
SR10 over a period of time and you want to share files between 
SR10 and non-SRIO nodes, you should ensure that all non-SRIO 
nodes have system software of SR9.7 or later vintage. For 
information about transition to SR 10 and about operating an 
environment with SR9.7 and SR10 nodes, see Making the Transi- 
tion to SR10 Operating System Releases. For information about 
installing software, see Installing Software with Apollo’s Release 
and Installation Tools . 



5.1 UNIX Protection 

The UNIX protection scheme is based on owner and group IDs. Every file system object 
has associated with it an owner ID and a group ID. Every process has four IDs: a real 
owner ID, an effective owner ID, a real group ID, and an effective group ID. Real IDs 
always represent the actual owner and group of the process; effective IDs are used by the 
system for checking rights. 
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5.1.1 Protection Modes 



Each file and directory has permissions for three categories of users: owner, group, and 
others. These permissions are represented as a UNIX mode, an octal number constructed 
from the logical OR of the following bits: 

4000 set user ID on execution 

2000 set group ID on execution 

1000 sticky bit 

0400 read by owner 

0200 write by owner 

0100 execute by owner 

0040 read by group 

0020 write by group 

0010 execute by group 

0004 read by others 

0002 write by others 

0001 execute by others 



For example, mode 640 allows the owner to read and write, the group to read only, and 
others no access at all. 



The UNIX command Is, when given the -1 option, reports an object’s octal mode in the 
form 



-rwxrwxrwx 

where each rwx sequence stands for the set of permissions available to the owner, the 
group, and others, respectively. (The initial hyphen indicates that the object is an ordinary 
file. For a directory, the initial character is the letter “d”; for a symbolic link, it is the 
letter “P.) Mode 640, for example, appears as 



-rw-r- 



Table 5-1 shows these rights and their meanings for files and directories. 

Table 5-1. UNIX Permissions 





File 


Directory 


B 


Read 


List entries 




Write 


Add, delete, or change 






entries 


X 


Execute 


Search 
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5.1.2 The setuid and setgid Bits 



The 4000, 2000, and 1000 bits in a protection mode have meaning only for executable 
files. They affect the behavior of a file when a user executes it. 

The 4000 bit is the setuid bit. If you execute a file that has this bit on, the operating 
system sets the effective user ID of the process to the owner ID of the file. Similarly, the 
2000 bit is the setgid bit. It sets the effective group ID to the group ID of the file. 

The Is command reports the setuid (or setgid) bit with the letter “s” in place of the “x” 
for execution by owner (or group). Though Is displays them in place of the “x,” these bits 
do not affect permission to execute the file. The operating system always checks the “x” 
bit. 

For example, if a program has the protection mode 6711, the owner ID pooh, and the 
group ID bears, Is -1 reports its protection as 

-rws — s — x 

The program always executes as though it were invoked by user pooh and group bears. 
The 1000 bit is the sticky bit. On Domain systems, this bit has no effect. 

5.1.3 Checking Permissions 

When a process attempts to access a file system object, the operating system checks per- 
missions in order: first owner, then group, and finally others. The first matching permis- 
sions apply. Permissions for the owner apply to any process whose effective user ID 
matches the object’s owner ID. Group permissions apply to any process whose effective 
group ID matches the object’s group ID and whose user ID does not match the object’s 
owner ID. Permissions for others apply to all other processes. 

For example, suppose the file tarts has the owner ID jack, the group ID hearts, and the 
protection mode 640. With the -1 and -g options, Is will show complete protection infor- 
mation for tarts: 

$ Is -lg tarts 

-rw-r 1 jack hearts 3474 Feb 29 10:54 tarts 

Processes with an effective user ID of jack will have both read and write permissions for 
tarts. Other processes will have read permission if their effective group ID is hearts and 
otherwise will have no access at all. 

The /etc/passwd file specifies a default group for each user. Additional groups can be 
specified in the /etc/group file. Under SysV, users can invoke the newgrp command to 
change their effective group IDs. Under BSD, a user effectively has membership in several 
groups at once: the default group specified in the passwd file and any others specified in 
the group file. 
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In Domain/OS, the PROJLIST environment variable determines which scheme for group 
membership applies. PROJLIST is set by default in the BSD operating environment. In 
other operating environments you can set it optionally. ( See Chapter 4, Subsection 4.2.4 
for details.) 

Because the operating system always applies the first matching permissions, it is possible for 
owner of a file to have fewer permissions than other users on the system. Mode 477, for 
instance, gives the owner read rights only, but gives everyone else all rights. 



5.1.4 Assigning and Changing Permissions 

A newly created object inherits its owner and group IDs from the process that creates it. 
(Except that under 4.3BSD, an object inherits the group ID from the parent directory, the 
directory where the object is created.) 

The permissions for a newly created object can be specified by the creating process, 
through the mode argument to system calls such as mkdir or open. System calls that do 
not take a mode argument create objects with mode 111 . In both cases, the permissions 
specified by the creating call are then filtered through the umask of the process. The 
umask is a bitmask that specifies permissions to be disallowed for any objects created by 
the process. For example, if a process with a umask of 022 creates an object via an open 
call with a mode of 770, the object will have a permissions mode of 750. 

Only an object’s owner or the super-user can change the IDs and permissions associated 
with the object. (The super-user, which we discuss in Subsection 5.4.1, has rights outside 
the normal protection model.) On vanilla 4.3BSD systems, only the super-user can change 
the owner ID of an object. However, Domain/OS BSD does not implement this restriction. 

5.1.5 Utilities 

This subsection surveys the UNIX utilities for inspecting and modifying protection. See the 
BSD Command Reference and the SysV Command Reference for detailed descriptions. 

The umask command (built in to the Aegis shell as well as the UNIX shells) sets or 
displays the value of the umask. The chmod command changes the permissions mode of a 
file or directory; chown changes the owner ID, and chgrp command changes the group 
ID. To display the protection of an object, you can use Is with the -1 and -g options. 

Figure 5-1 illustrates the use of these utilities. In this example, files are created via the 
touch command, which uses the creat system call with a mode of 666. 
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$ umask 
0 

$ touch magritte 
$ Is -lg magritte 

-rw-rw-rw- 1 mk none 

$ umask 022 
$ touch dali 
$ Is -lg dali 

-rw-r — r — 1 mk none 

$ chmod 664 dali 
$ chgrp dds dali 
$ Is -lg dali 

-rw-rw-r — 1 mk dds 



0 Feb 5 14:48 magritte 



0 Feb 5 14:49 dali 



0 Feb 5 14:49 dali 



Figure 5-1. UNIX Protection Utilities 



The BSD Programmer's Reference and the SysV Programmer's Reference describe system 
calls pertaining to protection, including stat, chmod, chown, and umask. 



5.2 Domain/OS Protection 



The SR10 Domain/OS protection model incorporates UNIX semantics and extends them 
with Access Control Lists (ACLs) . The Domain/OS model is thus a superset of the UNIX 
model, as shown in Figure 5-2. 



Domain/OS 

Protection 



UNIX 

Protection 



Figure 5-2. Domain/OS and UNIX Protection 
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5.2.1 ACL Structure 



Each file system object has an ACL that defines who can perform what operations on that 
file or directory. An ACL contains a number of entries. Each ACL entry has two parts: a 
Subject Identifier (SID) and a set of access rights. 



Subject Identifiers 

An SID is a specifier consisting of fields for a person, a group, and an organization. In 
ACL entries, each field of the SID can be either a name or a wildcard (%). Section 4.2 
describes SIDs in more detail. 



Access Rights 

Access rights describe the extent of an SID’s access to the associated object. Table 5-2 
lists the access rights for files and directories. 



Table 5-2. DomainlOS Access Rights 



Access 


File 


Directory 


r 


Read 


List entries 


w 


Write 


Add, delete, or change 
entries (including links) 


X 


Execute 


Search 


P 


Change protection 


Change protection 


k 


Keep (prevents deletion 
or change of name) 


Keep (prevents deletion 
or change of name) 



The r, w, and x rights are like their UNIX counterparts. 

In vanilla UNIX systems, only the owner of an object or the super-user can change the 
object’s protection. However, in Domain/OS, you can use the p access right to grant any 
SID permission to change the object’s protection. 

The k right in an ACL entry denies the specified SID the right to delete the object or to 
change its name, even if that SID has write permission for the parent directory. Under 
traditional UNIX semantics, all objects in a writable directory are deletable. However, in 
some situations, you want a directory to be writable, but you want to protect a particular 
file or subdirectory from deletion. You can establish this protection by setting the k right in 
the ACL for the file or subdirectory. 

If the ACL entry for an object contains both p and k rights, the specified SID can delete 
the object by using the -f option to either of the Aegis commands dlf and dlt. However, 
the UNIX command rm will not delete the object unless invoked by the super-user. 
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5-2.2 Types of ACL Entries 



An ACL must contain four required entries; in addition, it can contain extended entries. 
The required entries, which express UNIX protection information, are stored in the i-node 
of each file or directory to provide rapid access for operations like stat and chmod. 



Required Entries 

Every ACL contains at least four entries: one each for person, group, organization, and 
world. These are the four required entries in an ACL. The person, group, and world 
entries correspond to the UNIX concepts of owner, group, and other. The organization 
entry does not have a UNIX analog. 

A required ACL entry can be designated as an ignored entry. When the operating system 
checks permission to access the object, it ignores the entry. The acl command displays the 
entry with the word “ignored” in place of the access rights. 

The SIDs in the four required entries must be of the forms person. %.%, %. group. %, 

%.%. organization, and %.%.%. 



Extended ACL Entries 

In addition to the four that are required, an ACL can contain up to 22 extended entries. 
As we will explain in Subsection 5.3.2, the operating system applies a mask to the rights 
specified in extended entries when it checks permissions. 

The SIDs in extended entries can specify any combination of person , group , and organiza- 
tion, provided they do not duplicate any SIDs in the required entries. An extended entry 
cannot be ignored. 



An Example 

Figure 5-3 shows the ACL for a file as reported by the acl command. The left column 
shows SIDs; the right column shows the access rights associated with each SID. 



NOTE: All examples in this chapter use the acl utility. If you are working 

in a purely SysV environment (that is, you do not have a /com 
directory), use the lsacl command (see the lsacl manual page). 
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$ acl bar 
Acl for bar: 
Required entries 


mk . % . % 


prw — 


%.dds.% 


-rw — 


%.%. r_d 


[ignored] 


%.%.% 


-r 


Extended entry rights mask: 


-r 


Extended entries 


%. backup. % 


-r 


curly. stooges .% 





Figure 5-3 . An ACL 



5.2.3 Types of ACLs 

There are four types of ACL: the file ACL, the directory ACL, the initial default file 
ACL, and the initial default directory ACL. The first type is associated with files; the other 
three are associated with directories. ACLs of all four types must contain the required 
entries for owner, group, organization, and world. 

The file ACL controls access to the file with which it is associated. 

The directory ACL controls access to the directory with which it is associated. 

The initial file ACL determines the protection for files created within a directory. 

The initial directory ACL determines the protection for subdirectories created within a 
directory. 

Initial ACLs determine the protection assigned to newly created files and directories. 
Subsection 5.2.5 discusses in detail the role of initial ACLs. 

5.2.4 How ACLs are Interpreted 

The operating system associates each process with an SID. When a process attempts to 
access a file or directory, the operating system compares the process’ SID with the entries 
in the ACL for the file or directory; it applies the access rights specified in the first entry 
whose SID matches the process’ SID. If the rights allow the requested mode of access, the 
process gains access; if not, access is denied. 

Because the first matching ACL entry determines a process’ access to an object, the order 
of ACL entries is important. In general, ACL entries are ordered from the most specific to 
the least specific, with special precedence for required entries. The person field is more 
specific than the group field, which in turn is more specific than the organization field. 



5-8 



Protection of Files and Directories 





Figure 5-4 illustrates the rules for ordering of ACL entries. 



mk.%.% 


prwx- 


(required) 


mk. dds . r_d 


prwx- 




mk.dds.% 


prwx- 




mk . % . r_d 


prwx- 




user. unix. % 


-r 




user.%.% 


-r 




%.unix.% 


-rwx- 


(required) 


%.dds.r_d 


-rwx- 




%. dds .% 


-rwx- 




% . % . r__d 


-r-x- 


(required) 


%.%. legal 


-r 




%.%.% 




(required) 



Figure 5-4. Effective Order of Entries in an ACL 

Note that Figure 5-4 shows the effective order of ACL entries but does not correspond to 
the output of the acl command; acl displays extended entries separately from required 
entries. Figure 5-5 shows the same ACL, as acl would display it. 



$ acl foo 




Acl for foo: 




Required entries 




mk . % . % 


prwx- 


%.unix.% 


-rwx- 


% . % . r_d 


-r-x- 


%.%.% 




Extended entry rights mask: 


prwx- 


Extended entries 




mk.dds.r_d 


prwx- 


mk.dds.% 


prwx- 


mk . % . r_d 


prwx- 


user. unix. % 


_ r 


user.%.% 


-r 


%. dds . r_d 


-rwx- 


%. dds .% 


-rwx- 


%.%. legal 


-r 



Figure 5-5. An ACL as Displayed by the acl Command 

5.2.5 How ACLs are Assigned to New Files and Directories 

When a process creates a file or directory, the operating system assigns an ACL to the new 
object. Three factors govern the assignment of ACLs: 
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• The protection mode, if any, specified by the program creating the object 
o The umask, if any, of the process creating the object 

• The initial ACLs of the parent directory, the directory in which the object is 
created 



Creation Mode and the umask 

Some UNIX system calls, including open and mkdir, take a mode argument that allows 
you to specify a protection mode for a newly created object. Some other UNIX system 
calls and all Aegis system calls specify the widest possible permissions, allowing all forms of 
access for all users. In either case, this creation mode is filtered through the umask of the 
process, as Subsection 5.1.4. explains. 

In Domain/OS, the low-order octal digit in the mode and the umask applies both to the 
required organization entry and to the %.%.% entry. The middle digit applies to the re- 
quired group entry. The high-order digit applies to the required person entry. 

The permissions that result from application of the umask to the creation mode are either 
assigned to the new object or overridden by entries in the initial file or directory ACL of 
the parent directory. We refer to the first mechanism as “inheritance from the process” 
and the second as “inheritance from the parent directory.” The choice between these 
mechanisms is specified within the initial ACL itself. 



Initial ACLs 

Domain/OS allows the SID and/or the rights of a required ACL entry to be inherited either 
from the creating process or from the parent directory. Inheritance is specified as part of 
the initial ACLs of the parent directory and can apply to the SID, to the rights, or to both 
parts of an entry. 

Figure 5-6 shows an initial file ACL that implements BSD protection semantics. The rights 
for the required organization entry are ignored. All other SIDs and rights are inherited 
from the creating process except for the group SID, which derives from the parent direc- 
tory. 



$ acl -if figaro 

Initial (default) acl for files 


created under figaro 


Required entries 


For the current process: 


[from process] 


[specified by process] mk.%.% 


%. dds .% 


[specified by process] 


% . % . r_d 


[ignored] 


%.%.% 

Extended entry rights mask: 


[specified by process] 



Figure 5-6. Initial File ACL Implementing BSD Inheritance 



As Figure 5-6 shows, acl reports under the heading “For the current process” the particu- 
lar SIDs that will be inherited if the current process creates an object. 



/ 
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The edacl command has options that set inheritance of ownership or permissions in the 
initial ACLs of a directory. However, you should not ordinarily need to use these options; 
when Domain/OS software is installed on your node, the initial ACLs of your directories 
are set to implement the inheritance mechanism appropriate for your environment. The 
chad command allows you to change easily the inheritance semantics for any particular 
directory. 

5.2.6 Utilities 

This subsection surveys the utilities that deal with ACLs. 

The Aegis operating environment provides the utilities acl and edacl. You can use acl to 
display an ACL or to copy an ACL from one object to another. You can use edacl to edit 
ACLs. 

In all three of the operating environments, the utilities chad, Isacl, and cpacl are available 
in /usr/apollo/bin. These tools offer functionality similar to that of the Aegis acl and edacl 
utilities but user interfaces similar to those of the UNIX chmod, Is, and cp utilities. 

If you use BSD or SysV UNIX protection without any of the Domain/OS extensions, you 
will not need to deal with ACLs at all. See Subsection 5.1.5 for a survey of the UNIX 
protection utilities. 



5.3 How UNIX Modes are Derived from ACLs 



This section describes how Domain/OS protection is translated into UNIX protection. 

Domain/OS derives the modes that it supplies to UNIX programs and calls from the access 
rights in the ACL. If the protection of an object involves Domain/OS extensions to the 
UNIX protection model, the ACL information might not map directly to UNIX modes. In 
such cases, the operating system will over-represent rather than under-represent the access 
available when it reports permissions, and it will over-restrict rather than under-restrict 
access when it sets permissions. 

NOTE: The information in this section is important only for those who 

use the Domain/OS extensions to UNIX protection. Vanilla 
UNIX protection behaves as you would expect on other UNIX 
systems. 

5.3.1 Permissions for Owner and Group 

As Figure 5-7 shows, permissions for the owner and group of an object are those specified 
in the required ACL entries for the person and group. 
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$ acl foo 
Acl for foo: 
Required entries 


mk.%.% 




prwx- 


%. dds .% 




prw — 


%.%. r_d 




-rw — 


%.%.% 






Extended entry rights 


mask: 


-rwx- 


Extended entries 


user.%.% 




X- 


%.osdev.% 




-rw — 


%. backup. % 




-r 


$ /bin/ls -lg foo 


-rwxrw-rwx 1 mk 


dds 


0 Nov 10 17:35 foo 



Figure 5-7. ACL Entries and UNIX Permissions for a File 

5.3.2 Permissions for Others 

Since ACLs do not provide a direct equivalent to UNIX “other” rights, the operating 
system derives these rights from information in the ACL. The ACL entries that determine 
UNIX “other” rights are the required organization entry, the required world entry, and any 
extended entries— that is, all except the required person and group entries. 

To expedite the mapping of ACL information to UNIX rights, the operating system main- 
tains for every file or directory a set of rights that summarizes the permissions allowed by 
extended entries. These rights are reported in the output of acl as the “extended entry 
rights mask” and in the output of lsacl -1 as the “extended entry mask.” Unless otherwise 
set by a chmod call or command, the mask is the logical OR of all rights in any extended 
entries. 

The remainder of this subsection discusses how the rights mask, the org rights, and the 
world rights are used when the operating system reports, checks, or sets UNIX rights. 



Reporting Permissions 

When UNIX “other” rights are required by a command such as Is or a call such as 
stat(2), the operating system computes and reports the logical OR of the following: 

• The rights in the required org entry 

• The rights in the required world entry 

• The extended entry rights mask 

In Figure 5-7, for example, Is reports “other” rights as rwx because each of these rights is 
available to some SID other than the owner and the group, even though none of those 
SIDs has all of the rights. 
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Setting Permissions 

The rights mask reflects changes you make via edacl or chad to the extended entries in 
an object’s ACL. You can set the mask itself, independently of any ACL entries, via 
chmod. 

If you use edacl or chad to edit extended entries in the object’s ACL, the operating 
system recomputes the rights mask by taking the OR of all rights in the extended entries. 
The mask does not change if you edit only required entries. 

If you use the chmod call or command to change the rights for “others” on the object, the 
operating system implements the change as follows: 

® It sets the rights mask to match the rights you specified for “others.” 

® It sets “world” (%.%.%) rights to those you specified for “others.” 

® It sets the required org entry to be ignored. 

© It does not change any extended entries. 

As a result, no SID can have any rights not allowed in the chmod call or command. 

Figure 5-8 illustrates the use of chmod to change UNIX group and “other” rights on a 
file. 



Checking Permissions 

When it checks permissions for a extended entry, the system takes the logical AND of the 
rights mask and the permissions in the entry. Thus, SIDs in extended entries are allowed 
at most the access permitted by the rights mask. 

After the chmod command in Figure 5-8, for example, %.osdev.% and %. backup. % can 
only read foo, and user.%.% can only execute it. The w in the entry for %.osdev.% is 
masked. 
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$ acl foo 
Acl for foo: 
Required entries 










mk . % . % 




prwx- 






%.dds.% 




prw — 






%.%. r_d 




-rw — 






%.%.% 

Extended entry rights 
Extended entries 


mask: 


-rwx- 






user .%.% 




x- 






%. osdev.% 




-rw — 






%. backup. % 




-r 






$ /bin/ls -Ig foo 
-rwxrw-rwx 1 mk 


dds 


0 Nov 10 


17:35 


foo 


$ /bin/chmod 775 foo 
$ acl foo 
Acl for foo: 
Required entries 










mk . % . % 




prwx- 






%. dds .% 




-rwx- 






% . % . r_d 




[ ignored] 






%.%.% 




-r-x- 






Extended entry rights 
Extended entries 


mask: 


-r-x- 






user .%.% 




x- 






%. osdev .% 




-rw — 






%. backup. % 




-r 






$ /bin/ls -lg foo 
-rwxrwxr-x 1 mk 


dds 


0 Nov 10 


17:35 


foo 



Figure 5-8. Use of chmod to Set Permissions 
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5.4 Special Groups and Accounts 

This section discusses special groups and accounts that you can use in managing Domain 
systems. These groups and accounts are reserved: they are added automatically and per- 
manently to the registry database when the database is initialized. Subsection 4.2.3 gives a 
complete list of reserved names and accounts; here we discuss only those which pertain 
directly to the protection of system software. 

5.4.1 The root Person and the locksmith Group 

The operating system provides a special super-user named root. The root person is the 
most powerful on the system. It overrides all protections in the ACL mechanism. The root 
person always has the UNIX user ID 0. 

Use of root accounts should be carefully controlled. We suggest strongly that you assign 
passwords to root accounts, restrict knowledge of the passwords, and change the passwords 
periodically. 

To use a root account, you can either log in as a root user or invoke the UNIX su com- 
mand to switch your user ID to root. 

Domain/OS also provides a super-user group named locksmith. Accounts of the form 
%. locksmith. % have the same overriding privileges as those of the form root.%.%. Of 
course, locksmith accounts warrant the same careful control. The locksmith group is not 
allowed to appear on project lists, so members of this group do not carry super-user 
privileges unless they explicitly log in with locksmith accounts. 



5.4.2 The sys_admin, staff, and wheel Groups 

Any operating system includes software whose use should be restricted. In Domain/OS, 
access to system software (both programs and data files) is restricted to persons such as 
root and bin or groups such as sys_admin, staff, or wheel. To protect your system soft- 
ware from corruption or deletion, you should create accounts with these persons and 
groups only for users who need to have access to system software. 

5.4.3 The server Group 

The /etc/server shell command and the cps Display Manager command create server 
processes and assign to them the SID user.server.none. Processes started via server or 
cps run independently of log-in activity. 

When you log out, the DM does not terminate any process that run with server group 
identity. Therefore, we recommend that you do not create any accounts with the server 
group. 
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5.4.4 The user.none.none SID 



The registry database contains a reserved account with the SID user.none.none. In the 
event that no registry servers are available, the operating system will allow anyone to log in 
under this SID without giving a password. This is the only SID under which you can log in 
when the registry is unavailable. Of course, when a registry server is available, the password 
is required. 

You can use ACLs to limit the rights available to this SID. 



5.5 Backups 

Any user performing a backup must have the following access rights: 

• Read access to all files and directories being backed up 

• Write access to the backup_history file in the directory at the top of any tree to 
be backed up 

• Execute (that is, search) access to all directories in the pathnames of objects being 
backed up 



You can meet these requirements simply by performing all backups as root. If you prefer 
not to give root accounts to everyone who performs backups, we suggest the procedure 
below, which enables any %. backup account to run the backup utility with root privileges. 
The procedure creates a copy of wbak that runs with its user ID set to root and can be 
executed only by members of the group %. backup. 

1. Use the edrgy command to create accounts with the group name backup. 

2. Make a copy of the wbak utility. Set its protection to be setuid, owned by the 
root person and the backup group, and executable only by root and %. backup. 
(You must use a root or %. locksmith account to set the protection.) 

$ cd /usr/apollo/bin (UNIX environments) 

$ cp wbak wbak.priv 
$ chown root wbak.priv 
$ chgrp backup wbak.priv 
$ chmod 4550 wbak.priv 

$ wd /usr/apollo/bin (Aegis) 

$ cpf wbak wbak.priv 

$ edacl -p root prx -g backup rx -o none -ignore -w -none -setuid 
wbak.priv 

You should perform Step 2 on every node that will run backups. Now the wbak.priv 
copies, executable only by root and %. backup accounts, will run as root. The original 
copies of wbak remain executable by any user, but without root privileges. 
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5.6 Protected Subsystems 



A protected subsystem associates a set of data files (subsystem data objects) with programs 
(subsystem managers) that have special access rights to those files. Using Your Aegis 
Environment describes how to create protected subsystems. In this section, we discuss the 
login protected subsystem. 

The following list shows the shell commands that are part of the login subsystem. 

• The login command allows users to change their SIDs while logged in. 

• The /sys/siologin/siologin command allows users to log in to a Domain node via a 
terminal or modem attached to a serial I/O (SIO) line. 

• The /sys/spm/spmlogin command allows users to log in to one Domain node from 
another via the crp -on command. 

Refer to the Aegis Command Reference for information about the shell commands listed 
above. 

A user must “enter” a subsystem in order to set its attributes. Permission to enter a subsys- 
tem requires read and execute rights on the file /sys/subsys/subsystem. Figure 5-9 shows 
the ACL for the login subsystem. 



$ acl /sys/subsys/Iogin 




Acl for /sys/subsys/login: 




Subsystem login manager 




Required entries 




root .%.% 


pr-x — 


%. sys_admin.% 


pr-x — 


% . % . none 


-r 


%.%.% 


-r 


Non-required entry rights mask: 





Figure 5-9. ACL for the login Subsystem 



5.7 Control of Remote Access 

The Iprotect command and the -lao option to edacl allow you to control access from 
remote machines to objects on your machine. 

The node_owners file in ‘node_data determines who can run Iprotect on a node and also 
controls rights to perform other operations such as killing processes. 
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5.8 Installation and Protection 



The invol system utility sets protection on some system software. Other system software is 
protected as it is installed. You should not alter this protection because the operating 
system depends on it. For example, some UNIX subsystems require that programs, data 
files, and directories be owned by particular users and groups or assigned particular permis- 
sions. 

Note that protection model used and implemented by SR10 installation procedures depends 
on inheritance and the type of inheritance depends on how the disk was invol’d. You 
should be aware that, following installation, certain directories are not protected by inheri- 
tance, including ’node_data and /systest. 

Refer to Installing Software with Apollo's Release and Installation Tools for a description 
of how protection is inherited during installation. Refer to the BSD and SysV Command 
References for details on invol. 



5.9 Registries and Protection 

The registry database is protected in ways that do not use ACLs directly. Every entry in 
the registry database has an owner with rights to modify information pertaining to the 
entry. Owners of registry information are specified by SIDs; these can include wildcard (%) 
fields. See Chapter 4 for complete information about the registry. 

□□ 

□□ 
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Chapter 6 
Line Printer Management 
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The line printer (lp) system is a set of commands that perform various spooling functions 
for SysV. Because the primary lp application is offline printing, this document focuses 
mainly on spooling to line printers. The lp system allows system administrators to customize 
the system to spool to a collection of line printers of any type, as well as to group printers 
into logical classes. 

In addition, you can 

• Queue and cancel print requests 

• Prevent and allow queuing to devices 

® Start and stop Ip from processing requests 

• Change configuration of printers 

• Find the status of the lp system 

This chapter describes the role of an Ip administrator in configuring and administering lp 
for SysV. 



6.1 Definitions 

Several terms must be defined before we present a brief summary of the lp commands. 

The lp system makes a distinction between printers and printing devices. A device is a 
physical peripheral device or a file and is represented by a full system pathname. A 
printer is a logical name that represents a device. At different points in time, a printer can 
be associated with different devices. 

A class is a name given to an ordered list of printers; if you specify a class when you 
submit an lp request, the request will print on the first available printer in that class. Every 
class must contain at least one printer, but classes themselves are optional. Each printer 
can be a member of zero or more classes. 
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A destination is a printer or a class. One destination can be designated as the “system 
default destination.” The lp(l) command will direct all output to this destination unless 
you specify otherwise. Output directed to a specific printer will print only on that printer. 

Each invocation of lp creates an output request that consists of the files to be printed and 
options from the lp command line. An interface program that formats requests must be 
supplied for each printer. The lp scheduler, lpsched(lM), services requests for all 
destinations by routing requests to interface programs to perform the printing on devices. 
An lp configuration consists of devices, destinations, and interface programs. 



6.2 Commands Available to All Users 

The following commands are generally available to all users: 

• lp(l) — Requests that a file or files be printed. It creates an output request and 
returns a request ID of the form 

dest-seqno 

where seqno is a unique sequence number across the entire lp system and dest is 
the destination to which the request was routed. 

• Cancel (1) — Cancels lp requests. You identify the requests to be canceled by 
request ID(s) (returned by lp) or printer name(s). If you specify a printer name, 
all requests printing on the named printer(s) are canceled. 

• Disable(l) — Stops lpsched from routing output requests to printers. 

• Enable (1) — Allows lpsched to route output requests to printers. 



6.3 Commands Available to lp Administrators 

Many lp functions are restricted, requiring that you be logged in as either the super-user 
or as lp. All lp files and commands are owned by lp except for lpadmin and lpsched, 
which are owned by root. The following commands, which are for lp administrators, are 
described in more detail later in this chapter: 



• lpadmin(lM) — Modifies the lp configuration. Many features of this command 
cannot be used when lpsched is running. 

• lpsched (1M) — Routes output requests to interface programs, which perform the 
actual printing. 

• lpshut(lM) — Stops lpsched. All printing activity is halted, but other lp 
commands can still be used. 



6-2 Line Printer Management 





• accept(lM) — Allows lp to accept output requests for destinations. 

• reject(lM) — Prevents lp from accepting requests >r destinations. 

• Ipmove(lM) — Moves output requests from one destination to another. Whole 
destinations can be moved at one time. This command cannot be used when 
Ipsched is running. 



6.4 Setup 

Since many of the administrative functions require that you be logged in with the user 
name lp, a log-in account for lp must exist on your system. If there is not already such 
an account, you should create one before you attempt to configure the system. 



The lp subsystem is made up of the lp commands mentioned above, and a directory, 
/usr/spool/lp. The administrative commands reside in the directory /usr/lib, the user-level 
commands reside in /usr/bin, and the configuration information and spool directories 
reside in /usr/spool/lp. Figure 6-1 lists the files and directories in the /usr/spool/lp 
directory. 



-rwxrwxrwx 


1 


root 


573384 


Dec 


9 


08:14 


FIFO 


-rw-r — r — 


1 


IP 


4 


Dec 


6 


13:39 


SCHEDLOCK 


drwxr-xr-x 


1 


lp 


1024 


Nov 


25 


15:47 


class 


-rw-r — r — 


1 


lp 


2 


Dec 


2 


11:30 


default 


drwxr-xr-x 


1 


lp 


1024 


Dec 


2 


11:07 


interface 


-rw-r — r — 


1 


lp 


689 


Dec 


9 


07:25 


log 


drwxr-xr-x 


1 


lp 


1024 


Dec 


2 


11:07 


member 


drwxrwxrwx 


1 


lp 


1024 


Nov 


25 


16:18 


model 


-rw-r — r — 


1 


lp 


992 


Nov 


30 


15:42 


oldlog 


-rw-r — r — 


1 


lp 


376 


Dec 


9 


08:13 


outputq 


-rw-r — r — 


1 


lp 


800 


Dec 


9 


08:13 


pstatus 


-rw-r — r — 


1 


lp 


600 


Dec 


9 


08:13 


qstatus 


drwxr-xr-x 


1 


lp 


1024 


Dec 


2 


11:07 


request 


-rw-r — r — 


1 


lp 


3 


Dec 


9 


07:23 


seqf ile 



Figure 6-1. The lusr/spoolllp Directory 

Since you may alter the files in this directory in the course of configuring the lp system for 
your network, we suggest that, before you begin, you make a backup copy of this entire 
directory. 
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Once you’ve done that, add the following lines to your system administrator’s node 
/sys/node_data/etc.rc file to start the Ip scheduler each time the system is started. 



rm -f /sys5/usr/spool/lp/SCHEDL0CK 
/sys5/usr/lib/lpsched 
echo "lp scheduler started" 

NOTE: The spooling directory (/usr/spool/lp) and the lp scheduler 

(/usr/lib/llpsched) must run on the same node, usually the 
master system administrator node. 



6.5 Configuring lp with the lpadmin Command 

To change the lp configuration, use the lpadmin command. The lpadmin command will 
not attempt to alter the lp configuration while lpsched is running, except where explicitly 
noted in the following subsections. 

6.5.1 Introducing New Destinations 

The following information information must be supplied to lpadmin when you introduce a 
new printer to the system: 

• The printer name (-p printer) . An arbitrary name that must 
— Be no longer than 14 characters. 

— Consist solely of alphanumeric characters and underscores 
— Not be the name of an existing lp destination (printer or class) 

• The device associated with the printer (- ydevice ) . This is the pathname of a 
hard-wired printer, a log-in terminal, or other file that is writable by lp. If you 
specify a Domain prf model, set device to /dev/null 

• The printer interface program — This program can be 

— Selected from a list of model interfaces supplied with lp (-m model) 

— The same interface that an existing printer uses (- eprinter ) 

— A program supplied by the lp administrator (-i interface ) 

You can also indicate whether the new print destination is a hard-wired or log-in terminal, 
and the class to which the print destination should be assigned. 
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Use the -h option of the lpadmin command to indicate that the print device is hard wired; 
use the -1 option to indicate that the print device is the pathname of a log-in terminal. (-1 
is the default). 

Because device names for log-in terminals can be (and usually are) associated with 
different physical devices from day to day, Ipsched automatically disables these devices 
each time it starts running. The lpstat command reports this when it indicates printer 
status as shown in the example below, where a is the printer name. 



$ lpstat -pa 

printer a (log-in terminal) disabled Oct 31 11:15 - 
disabled by scheduler: log-in terminal 

Use the -c class option to add the new printer device to an existing class or to a new class. 
New class names must conform to the same rules as for new printer names. 



Example 1 

The following example creates a hard-wired printer named prl whose device is /dev/siol 
and whose interface program is the model hp interface: 

$ /usr/lib/lpadmin -pprl -v/dev/siol -mhp 



Example 2 

The following example adds a printer, which is also a log-in terminal, named pr2 whose 
device is /dev/sio2 and whose interface is a variation of the model prx interface: 



$ cp /usr/spool/lp/model/prx xxx 
< edit xxx > 

$ /usr/lib/lpadmin -ppr2 -v/dev/sio2 -ixxx -1 



Example 3 

The following example creates a printer named pr3. This printer prints to a Spin writer 0 
served by the prf print facility. Printer pr3 will be added to a new class, called ell, and 
will use the spin interface. 

$ /usr/lib/lpadmin -ppr3 -v/dev/null -mspin -cell 



0 Spin writer is a registered trademark of NEC Corp. 
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6.5.2 Modifying Existing Destinations 



You always modify an existing destination with respect to its printer name (-p printer). 
Modifications can be one or more of the following: 

1. The device for the printer can be changed (-v device). If this is the only 
modification, then this may be done even while lpsched is running. This facilitates 
changing devices for log-in terminals. 

2. The printer interface program can be changed (-m model, - eprinter , -i interface ). 

3. The printer can be specified as hard wired (-h) or as a log-in terminal (-1). 

4. The printer can be added to a new or existing class (-c class). 

5. The printer can be removed from an existing class (-r class). Removing the last 

remaining member of a class causes the class to be deleted if no print requests are 
pending for that class. 



Example 1 

The following example adds a printer named pr2 to class ell: 

$ /usr/lib/lpadmin -ppr2 -cell 

Example 2 

The following example changes pr2’s interface program to the model prx interface and 
adds the printer it to a new class called cl2: 

$ /usr/Sib/lpadmin -ppr2 -mprx -cc!2 
Printer pr2 is now a member of two classes, ell and, cl2. 



Example 3 

This example defines printer pr2 as a hard-wired printer: 
$ /usr/lib/lpadmm -ppr2 -h 

Example 4 

The following example adds printer prl to class cl2: 

$ /usr/Sib/lpadmin -pprl -ccl2 
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The members of class cl2 are now pr2 and prl, in that order. Requests routed to class cl2 
will be serviced by pr2 if both pr2 and prl are ready to print; otherwise, they will be 
printed by the first available printer in the class. 



Example 5 

The following example removes printers pr2 and pr3 from class ell: 

$ /usr/Sib/lpadmin -ppr2 -rcll 
$ /usr/lib/lpadmin -ppr3 -rcll 

Since pr3 was the last remaining member of class ell, the class is removed. 



Example 6 

This example adds pr3 to a new class called cl3. 



$ /usr/lib/lpadmin -ppr3 -ccl3 

6.5.3 Specifying the System Default Destination 

You can change the system default destination when Ipsched is running. For example ^o 
establish class ell as the system default destination, use the following command: 

$ /usr/lib/lpadmin -dell 

To establish no default destination, use the following command: 



$ /usr/lib/lpadmin -d 

6.5.4 Removing Destinations 

You can remove a class or a printer only if it has no pending requests. Pending requests 
can be canceled with cancel or moved to another destination with Ipmove. If the class or 
printer you remove is the system default destination, then the system will have no default 
destination until you explicitly define a new one. When the last remaining member of a 
class is removed, the class is also removed. Removing a class does not imply that the 
printers in that class were removed. 
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Example 1 

This example makes printer prl the system default destination: 

$ /usr/lib/lpadmin -dprl 

Example 2 

This example removes printer prl: 

$ /usr/lib/lpadmin -xprl 
Now there is no system default destination. 

If printer pr2 is removed: 

$ /usr/lib/lpadmin -xpr2 

Class cl2 is also removed since pr2 was its only member. 

If class cl3 is removed: 

$ /usr/lib/lpadmin -xcl3 

The class is removed, but printer pr3, a member of the class, remains. 



6.6 Making an Output Request with the lp Command 

Once Ip destinations have been created, you can request output by using the lp command. 
You use the request ID that is returned to see if the request has been printed or to cancel 
the request. 

The lp program determines the destination of a request by checking the following list in 
the order shown: 

1. If the user specifies -d dest on the command line, then the request is routed to 
dest. 

2. If the environment variable LPDEST is set, the request is routed to the value of 
LPDEST. 

3 If there is a system default destination, then the request is routed there. 

4. If no destination if found, the request is rejected. 
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Example 1 

This example prints two copies of file abc on printer xyz and titles the output “my file”: 



$ pr abc | lp -dxyz -n2 -t”my file” 



Example 2 

The following example prints a file named xxx on a Diablo 1640 printer called zoo in 
12-pitch and writes to the user’s terminal when printing has completed: 

$ lp -dzoo -ol2 -w xxx 

In this example, “12” is an option that is meaningful to the model Diablo 1640 interface 
program that prints output in 12-pitch mode. 



6.7 Finding lp Status with lpstat 

The lpstat command is used to find status information about lp requests, destinations, and 
the scheduler. The status information for a request includes: 

• The request ID 

® The log-in name of the user 
® The total number of characters to be printed 

• The date and time the request was made 



Example 1 

This example lists the status of all pending output requests made by this user: 
$ lpstat 
Example 2 

This example lists the status of printers pi and p2: 

$ lpstat -ppl,p2 
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6.8 Canceling Requests with cancel 



Lp requests can be canceled by using the cancel command. The cancel command accepts 
request IDs and printer names as arguments. If you specify request IDs, the requests 
named by the request IDs are canceled. If you specify printer names, the requests 
currently printing on the named printers are canceled. Both types of arguments can be 
intermixed. 

If the user who is canceling a request is not the same one who made the request, then 
mail is sent to notify the owner of the request of the cancelation. The lp command allows 
any user to cancel requests in order to eliminate the need for users to find lp 
administrators when unusual output should be purged from printers. 



6.9 Allowing and Refusing Requests: accept and reject 

When a new destination is created, Ip will reject requests that are routed to it, until the Ip 
administrator invokes the accept command to allow lp to accept requests for that 
destination. 

Sometimes it is necessary to prevent lp from routing requests to destinations. If a printer 
has been removed or is being repaired, or if there are too many requests for it, you may 
wish to reject requests for those destinations, using the reject command. Use the accept 
command to allow requests again. 

The acceptance status of destinations is reported by the -a option of lpstat. 



Example 1 

This example causes lp to reject requests for destination xyz: 

$ /usr/lib/reject -r” printer xyz needs repair” xyz 

Any users that try to route requests to xyz will receive the following message: 

lp: can not accept requests for destination "xyz" 
— printer xyz needs repair 



Example 2 

The following example allows lp to accept requests routed to destination xyz: 
$ /usr/lib/accept xyz 
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6.10 Allowing or Inhibiting Printing: enable and disable 

The enable command allows the lp scheduler to print requests on printers. That is, the 
scheduler routes requests only to the interface programs of enabled printers. Note that it 
is possible to enable a printer and at the same time prevent further requests from being 
routed to it (using the reject command). 

The disable command undoes the effects of the enable command. It prevents the 
scheduler from routing requests to printers, regardless of whether lp is allowing them to 
accept requests. Printers may be disabled for several reasons including malfunctioning 
hardware, paper jams, and end-of-day shutdowns. If a printer is busy at the time it is 
disabled, then printing will halt. The halted request will be reprinted in its entirety either 
on another printer (if the request was originally routed to a class of printers) or on the 
same one when the printer is re-enabled. The -c option causes the currently printing 
requests on busy printers to be canceled, in addition to disabling the printers. This is useful 
if strange output is causing a printer to behave abnormally. 



Example 

The following example disables printer xyz because of a paper jam, checks the status of 
xyz, and finally enables printer xyz: 



$ disable -r”paper jam” xyz 

printer "xyz" now disabled 

$ lpstat -pxyz 

printer "xyz" disabled since Jan 5 10:15 - paper jam 

$ enable xyz 

printer "xyz" now enabled 



6.11 Moving Requests Between Destinations with Ipmove 

Occasionally, it is useful for lp administrators to move output requests between 
destinations. For instance, when a printer is down for repairs, it is desirable to move all of 
its pending requests to a working printer. Use the Ipmove command for this. The Ipmove 
command will refuse to move requests while the lp scheduler is running. If you move all 
requests from one printer to another, the printer from which the requests are moved is 
disabled. 



Example 1 

This example moves all requests for printer abc to printer xyz: 
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$ /usr/lib/lpmove abc xyz 

All of the moved requests are renamed, from abc-nnn to xyz-nnn. and destination abc is 
disabled. 



Example 2 

This example moves requests zoo-543 and abc- 1200 to printer xyz: 



$ /usr/lib/lpmove zoo-543 abc-1200 xyz 
The two requests are now renamed xyz-543 and xyz-1200. 



6.12 Stopping and Starting the Scheduler: lpshut and lpsched 

The lpsched command is the program that routes output requests made with lp through 
the appropriate printer interface programs to the printers. Each time the scheduler routes 
a request to an interface program, it records an entry in the log file, /usr/spool/lp/log. If 
a request has been restarted, there may be more than one entry in the log file that refers 
to the request. 

The log file entry contains 

• The log name of the user that made the request 

• The request ID 

• The name of the printer that the request is being printed on 

• The date and time that printing started 

The scheduler also records error messages in the log file. When lpsched is started, it 
renames /usr/spool/lp/log to /usr/spool/lp/oldlog and starts a new log file. 



6.12.1 Starting lpsched 

The lpsched process is normally started at boot time and continues to run until the node is 
shut down. The scheduler operates in the /usr/spool/lp directory. When it starts running, 
it will exit immediately if a file called SCHEDLOCK exists. Otherwise, it creates this file to 
prevent more than one scheduler from running at the same time. To start lpsched, use 
the command 



$ /usr/lib/lpsched 



6-12 Line Printer Management 





Shortly after this command is entered, lpstat should report that the scheduler is running. 

If not, a previous invocation of lpsched may have exited without removing SCHEDLOCK, 
so try the following: 



$ rm -f /usr/spool/lp/SCHEDLOCK 
$ /usr/lib/lpsched 

The scheduler should be running now. 

6.12.2 Checking the Status of lpsched 

No printing will be performed by the lp system unless lpsched is running. Use the 
following command to check the status of the lp scheduler: 



$ lpstat -r 

6.12.3 Stopping lpsched 

Occasionally, it is necessary to shut down the scheduler in order to reconfigure lp or to 
rebuild the lp software. The following command uses lpsched to stop running and 
terminates all printing activity: 



$ /usr/lib/lpshut 

All requests that were actually being printed will be reprinted in their entirety when the 
scheduler is restarted. 



6.13 Printer Interface Programs 

Every lp printer must have an interface program that does the actual printing on the device 
currently associated with the printer. Interface programs can be shell procedures, C 
programs, or any other executable program. The lp model interfaces are all written as shell 
procedures and can be found in the /usr/spool/lp/model directory. 

6.13.1 Printer Interface Invocation 

When lpsched routes an output request to a printer, the printer’s interface program is 
invoked in the directory /usr/spool/lp as follows: 

interface//? id user title copies options file ... 

Following is a description of each option and examples of how to use the syntax. 
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p The printer interface program name. 

id The request ID returned by Ip. 

user The log-in name of user who made the request. 

title Optional title specified by the user. 

copies Number of copies requested by user. 

options A blank-separated list of class or printer-dependent options specified 

by the user. 

file The full pathname of a file to be printed. 

The following examples are requests made by user “smith” with a system default 
destination of printer “xyz.” Each example lists an lp command line followed by the 
corresponding command line generated for printer xyz’s interface program: 



$ Ip /etc/passwd /etc/group interface /xyz xyz- 52 smith ” ” 1 ” ” /etc/passwd /etc /group 
$ pr /etc/passwd | Ip -t”users” -n5 interface /xyz xyz-53 smith users 5 ” ” 



$ Ip /etc/passwd -oa -ob interface/xyz xyz-54 smith ”” 1 "a b” /etc/passwd 

6.13.2 Printer Interface Standard Input and Output 

When the interface program is invoked, its standard input comes from /dev/null and both 
the standard output and standard error output are directed to the printer’s device. Devices 
are opened for reading as well as writing when file modes permit. In the case where a 
device is a regular file, all output is appended to the end of the file. 

6.13.3 The prf Command Support 

Several interface models have been provided to support the prf facility. These interfaces 
(p, ge, and spin) do not write to the standard output, but pipe data to the /com/prf 
command. These models can be customized to create new interfaces to support a variety of 
devices with the prf command. 

6.13.4 Directing Output to a Device 

If you choose to communicate to the device, you must supply the actual device name to 
the lpadmin command when you configure the system. In addition, you must modify the 
supplied model interface program(s) to pipe data through a supplied filter like 
/usr/lib/lpfilter or /usr/lib/prx, or a user-written filter. 
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The /usr/lib/lpfilter filter moves data to a printer from a model interface program, 
allowing you to de-couple the relationship between prf and model interface programs. 
Basically, lpfilter initializes the parameters for the port to match what is expected by the 
printer device and then reads from stdin and writes to stdout. 



The lpfilter Options 

Using lpfilter, you can choose to filter the bits (for example, turn line wrap on, indent, 
etc.) or you can simply transfer the raw (transparent) data to the printer. (Transfering raw 
data is appropriate for a PostScript* printer.) 

lpfilter takes the following options: 

-wi Paper width in inches (default is 8.5 inches). 

-lgt Paper length in inches (default is 11.0 inches). 

-cpi Characters per inch (default is 10 cpi). 

-Ipi Lines per inch (default is 6 lpi). 

-i Indent in inches (default is 0 inches). 

-t Size of tab expansion (default is 0 spaces). 

-w Line wrap (default is off). 

-tr Transparent mode (that is, move bits to the port without filtering) . 

-cf I/O control flags for printer (default is off) . 

-if I/O input control flags for printer (default is off) . 

-of I/O output control flags for printer (default is off). 

-If I/O line control flags for printer (default is off). 

See the the termio manual page in Chapter 9 for more information on I/O flags. Note 
that if the defaults are used for the I/O flags, lpfilter assumes the port has already been 
configured correctly. 



* PostScript is a registered trademark of Adobe Systems, Inc. 
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6.13.5 Interface Program Formatting 



Given the command-line arguments and the output directed to a device, interface 
programs format their output in any way they choose. 



6.13.6 Establishing Terminal Characteristics 

Interface programs must ensure that the proper stty modes (terminal characteristics such as 
baud rate, output options, etc.) are in effect on the output device. (This can be done in a 
shell interface only if the device is opened for reading.) Use the following command to 
take the standard input for the stty command from the device: 



$ stty mode ... <&1 

6.13.7 Printer Interface Program Return Codes 

When printing has completed, the interface program must exit with a code indicative of the 
success of the print job. Exit codes are interpreted by lpsched as follows: 

Code Meaning to lpsched 

0 The print job has completed successfully. 

1 to 127 A problem was encountered in printing this particular request (such as, 

too many nonprintable characters). This problem will not affect future 
print jobs. The lpsched process notifies users by mail that there was 
an error in printing the request. 

greater than 127 These codes are reserved for internal use by lpsched. Interface 
programs must not exit with codes in this range. 

When problems that are likely to affect future print jobs occur (for example, a device filter 
program is missing), the interface programs should disable printers so that print requests 
are not lost. When a busy printer is disabled, the interface program will be terminated 
with signal 15. 



□□ 

□□ 



6-16 Line Printer Management 




Chapter 7 
uucp Administration 



Contents 



7.1 Network Planning 7-2 

7.1.2 Extent of the Network 7-2 

7.1.2 Hardware and Line Speeds 7-2 

7.1.3 Maintenance and Administration 7-3 

7.2 The uucp Software 7-3 

7.3 Installation 7-4 

7.3.1 Apollo Configuration 7-5 

7.3.2 Differences between /dev/siox and /dev/ttyx Devices 7-6 

7.3.3 Password File 7-6 

7.4 Supporting Database 7-7 

7.4.1 Devices File 7-7 

Protocols 7-11 

7.4.2 Dialers File 7-11 

7.4.3 Systems File 7-14 

7.4.4 Dialcodes File 7-17 

7.4.5 Permissions File 7-18 

How Entries are Structured 7-18 

Considerations 7-19 

Options 7-19 

7.4.6 Poll File 7-25 

7.4.7 Devconfig File 7-25 

7.4.8 Sysfiles File 7-26 

7.5 Administration 7-27 

7.5.1 Cleanup 7-27 

Cleanup of Undeliverable Jobs 7-27 

7.5.2 Polling Other Systems 7-28 

7.5.3 Problems 7-28 

Out of Space 7-28 

Bad ACU and Modems 7-28 

Administrative Problems 7-28 

7.6 Debugging 7-29 





uucp Administration 



The uucp program is the central program in a group of programs that, together, permit 
communication between Domain systems by using either dial-up or hard-wired 
connections. SR 10 supplies the HoneyDanBer version of uucp. This version provides 
interoperability between SR9.7 and SR10 nodes and communicates with most versions of 
uucp, including Apollo pre-SRIO nodes, other HoneyDanBer uucp implementations and 
other uucp implementations (it does not support communications over TCP, TLI or X.25) 
This Apollo implementation of uucp also provides enhancements such as spool directory 
trees, better security, and error handling. 

This chapter describes how a uucp network is set up, the format of control files, and 
administrative procedures. You should be familiar with the manual pages for each of the 
uucp related commands. Other helpful external documentation on HoneyDanBer uucp 
include the following: 

® AT&T UNIX System V User's Guide 

• AT&T UNIX System V System Administrator's Guide 

• UNIX System Security , Patrick H. Wood and Stephen G. Kochan, Hayden Books 

• HoneyDanBer uucp — Bringing UNIX Systems into the Information Age , Bill 
Rieken and Jim Webb 

Refer to Making the Transition to SR10 Operating System Releases for more information 
on uucp interoperability in mixed networks (SR9.7 and SR10 nodes). 
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7.1 Network Planning 



There are several considerations you should take into account before configuring a 
network. These considerations are discussed below. 



7.1.1 Extent of the Network 

Before you set up the network configuration, you must make some basic decisions about 
access to processors in the network. If you control only one processor and are joining an 
existing network, then you must decide what level of access you will grant to other systems. 
Likewise, the other members of the network must make a similar decision for the system 
you control. 

You control system access by using the following: 

• The UNIX system passwd command to grant access to systems. 

• The file /usr/lib/uucp/Permissions to restrict access to specified parts of the file 
system tree. 

• The file /usr/lib/uucp/Systems on the local processor to determine how many 
other systems on the network you can reach. 

If you are setting up more than one processor, and thus controlling a larger portion of the 
network, you must make more decisions about the setup. For example, the network can be 
set up as a private network where only those machines under the direct control of the 
administrator can access each other. Granting no access to machines outside the network 
can be done if security is paramount; however, this is usually impractical. Very limited 
access can be granted to outside machines by each of the systems on the private network. 
Alternatively, access to/from the outside world can be confined to only one processor. This 
is frequently done to minimize the effort in keeping access information (passwords, phone 
numbers, log-in sequences, etc.) updated and to minimize the number of security holes for 
the private network. 



7.1.2 Hardware and Line Speeds 

The uucp system supports two means of interconnection: 

• Direct connection using a null modem cable 

• Connection over the Direct Distance Dialing (DDD) network 
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These methods of interconnection support intelligent auto-dial modems 



In choosing hardware, the equipment used by other processors on the network must be 
considered. For example, if some systems on the network have only 103-type (300-baud) 
data sets, then communication with them is not possible unless the local system has a 
300-baud data set connected to a calling unit. (Most data sets available on systems are 
1200-baud.) 

If hard-wired connections are to be used between systems, then the distance between 
systems must be considered since a null modem cannot be used when the systems are 
separated by more than several hundred feet. The limit for communication at 9600-baud is 
about 800 to 1000 feet. However, the RS-232 specification and Western Electric Support 
Groups only allow for less than 50 feet. Limited-distance modems must be used beyond 50 
feet as noise on the lines becomes a problem. 



NOTE: Ensure that you have getty or siologin monitoring the port to 

which uucp is connected. 



7.1.3 Maintenance and Administration 

There is a minimum amount of maintenance that must be provided in each system to keep 
the access files updated, to ensure that the network is running properly, and to track down 
line problems. When more than one system is involved, the job becomes more difficult 
because there are more files to update and because users are much less patient when 
failures occur between machines that are under local control. 



7.2 The uucp Software 

To call another system, the uucp(l) or uux(l) command queues users requests and 
spawns the uucico daemon. The uucico daemon initiates the call to another system and 
performs the file transfer. On the receiving side, uucico is invoked to receive the transfer. 
Remote execution jobs are actually done by transferring a command file to the remote 
system and invoking a daemon (uuxqt) to execute that command file and return the 
results. 
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7.3 Installation 



The uucp(l) package is installed as part of the standard UNIX environment. 

The following object modules are installed as part of standard installation: 

• uucp — The file transfer command. 

• uux — The remote execution command. 

• uucico — The uucp network daemon. 

• uustat — Network status command. 

• uucleanup — Clean-up command. 

• uuxqt — The remote execution daemon. 

• uucheck — The command that checks for the presence of the uucp 
system-required files and directories. 

• uuname — The command to list the names of systems known to uucp. 

• uusched — The uucp file transport scheduler. 

• uuencode — The uucp command that sends binary files to a remote system via 
mail. 

• uudecode — The uucp command that recreates the original file with the specified 
mode and name. 



NOTE: uuencode does not preserve Aegis file type information. The 

uudecode command always added produces files of type 
unstruct. Therefore, to transfer an obj type file, use the obty 
command to change the type to unstruct. Use uuencode on the 
file, tranfer it to the destination system, and uudecode it. Use 
the obty command to modify the type to obj. 
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The following shell scripts are installed as part of normal installation: 



© SetUp — Sets up all necessary uucp system files. 

Q Uutry — Starts a uucico for the specified system. 

© remote. unknown — Logs calls from unknown systems. 

o uudemon. admin — Sends uucp status information to the system administrator 
node. 

o uudemon. cleanup — Cleans up uucp directories. 

© uudemon. hour — Starts uusched and uuxgt. 
o uudemon. poll — Sets up for polling systems. 

o Maxuuxgts — Defines the maximum number of uuxgt programs that can run at 
one time. 

o Maxuuscheds — Defines the maximum number of unsched programs that can run 
at one time. 

o uulog — Prints log information for the specified system. 

© uuto and uupick — Public UNIX system to UNIX system file copy. 

The uucp programs look for the file, /usr/lib/uucp/sitename, to determine the uucp site 
name. This is an ASCII file containing the uucp site name and must be created by the 
system administrator. If this file does not exist, the site name is set to the node name 
returned by the gethostname call. 



7.3.1 Apollo Configuration 

In a Domain network, there is usually one node configured as the uucp “site.” Other 
nodes on the network are set up so that their /usr/spool/uucp and /usr/lib/uucp 
directories link to the uucp site. 

The uucp and uux programs perform file permission checking and queue requests to the 
/usr/spool/uucp directory for each node in the network. When the uucico program starts 
on the uucp site node, it looks in the /usr/spool/uucp directories for requests to perform. 
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7.3.2 Differences between /dev/siox and /dev/ttyx Devices 

The tty/sio ports used by uucp must be configured to be compatible with the attached 
modem (for example, baud rate, bits per character, parity). Although /dev/siox and 
/dev/ttyx (where x is the port number) refer to the same physical port, they are handled 
differently. Operations on /dev/siox ignore DCD (Data Carrier Detect) status while default 
operations on /dev/ttyx adhere to the UNIX conventions (such as requiring DCD to be 
high before completing an open of the device) . 

The uucp programs open the device with the 0_NDELAY flag, which causes the open to 
return without waiting for DCD. This enables either /dev/siox or /dev/ttyx devices to be 
used for both dialing out or receiving calls. However, it is recommended that /dev/ttyx 
devices be used exclusively for uucp (including cu and tip). This enables device locking 
to function properly. 

NOTE: To monitor the tty/sio port for incoming calls, add and entry to 

the /etc/ ttys file to start /etc/getty. It is recommended for the 
reasons stated above, that /dev/ttyx be used for getty. A port 
monitored by /etc/getty cannot be used to dial out on unless 
getty is suspended first. This can be done by using a script. 



7.3.3 Password File 

The registry contains the information necessary to generate the /etc/passwd file that 
contains password entries for remote uucp logins. These entries allow remote systems to 
call the local system. For example: 

nuucp : zaaAA: 6:1: uucp . Admin : /usr/spool/uucppublic : /usr/lib/uucp/uucico 

The uucico daemon is specified for the shell field, and the spool directory is specified as 
the working directory. There must also be an entry a uucp administrative login. This login 
is the owner of all the uucp object and spooled data files and is usually named uucp. For 
example, the following is a entry in /etc/passwd for this administrative login: 

uucp : zAvLCKp : 5 : 1 : uucp . Admin : /usr/ lib/uucp : 

Note that the standard shell is used instead of uucico. 

The log-in account for sites calling into the uucp site must have its shell defined to be 
/usr/lib/uucp/uucico. real. 
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7.4 Supporting Database 



The following Basic Networking Utilities support files are in the /usr/lib/uucp directory: 

• Devices — Contains information concerning the location and line speed of the 
automatic call unit, direct links, and network devices. 

© Dialers — Contains character strings required to negotiate with network devices 
(automatic calling devices) to establish connections to remote computers (non 
801-type dialers). 

• Systems — Contains information needed by the uucico daemon and the cu 
program to establish a link to a remote computer. It contains information such as 
the name of the remote computer, the name of the connecting device associated 
with the remote computer, when the computer can be reached, telephone number, 
login ID, and password. 

® Dialcodes — Contains dial-code abbreviations that may be used in the phone 
number field of Systems file entries. 

© Permissions — Defines the level of access granted to computers when they 
attempt to transfer files or remotely execute commands on your computer. 

© Poll — Defines computers that are to be polled by your system and when they are 
polled. 

® Devconfig — Used to configure utilities for the Basic Networking Utilities on a 
STARLAN NETWORK or some other transport provider that conforms to the 
AT&T Transport Interface. 

© Sysfiles — Assigns different or multiple files to be used by uucico and cu as 
Systems, Devices, and Dialers files. 

There are several other files that may be considered part of the supporting data base, but 
are not directly related to the process of establishing a link and transferring files. These 
files (Maxuuxqts, Maxuuscheds, and remote. unknown) are described in Section 7.3, 
“Installation.” 

Each of the supporting data base files is described below. 



7.4.1 Devices File 

The Devices file (/usr/lib/uucp/Devices) contains information for all devices used to 
establish a link to a remote computer, devices such as automatic call units, direct links, 
and network connections. 
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This file works closely with the Dialers, Systems, and Dialcodes files. Before you make 
changes in any of these files, you should be familiar with them all. A change to an entry in 
one file may require a change to a related entry in another file. 

Each entry in the Devices file has the following format: 

Type Line Line2 Class Dialer-Token-Pairs 
The meaning of each of these fields is: 

Type This field may contain one of two keywords (Direct or ACU), the name 

of a Local Area Network switch, or a system name. 

Direct This keyword indicates a Direct Link to another computer or 

a switch (for cu connections only). 

ACU This keyword indicates that the link to a remote computer is 

made through an automatic call unit (Automatic Dial 
Modem). This modem may be connected either directly to 
your computer or indirectly through a Local Area Network 
(LAN) switch. 

LANJSwitch This value can be replaced by the name of a LAN switch. 

micom and develcon are the only ones for which there are 
caller scripts in theDialers file. You can add your own LAN 
switch entries to the Dialers file. 

Sys-Name This value indicates a direct link to a particular computer. 

{Sys-Name is replaced by the name of the computer.) This 
naming scheme is used to convey the fact that the line 
associated with this Devices entry is for a particular computer 
in the Systems file. 

The keyword used in the Type field is matched against the 
third field of Systems file entries as shown below: 

Devices: ACU ttyll - 1200 penril 

Systems: eagle Any ACU 1200 3251 ogin: nuucp 

\ s sword : Oakgras s 

You can designate a protocol to use for a device within this 
field. See the “Protocols” section at the end of the 
description of this file. 

Line This field contains the device name of the line (port) associated with the 

Devices entry. For instance, if the Automatic Dial Modem for a 
particular entry was attached to the /dev/tty 11 line, the name entered in 
this field would be ttyll. 
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Line2 



If the keyword ACU was used in the Type field and the ACU is an 801 
type dialer, Line2 would contain the device name of the 801 dialer. (801 
type ACUs do not contain a modem. Therefore, a separate modem is 
required and would be connected to a different line, defined in the Line 
field.) This means that one line would be allocated to the modem and 
another to the dialer. Since non-801 dialers will not normally use this 
configuration, the Line2 field will be ignored by them, but it must still 
contain a dash (-) as a placeholder. 

Class If the keyword ACU or Direct is used in the Type field, Class may be 

just the speed of the device. However, it may contain a letter and a 
speed (for example, C1200, D1200) to differentiate between classes of 
dialers (Centrex or Dimension PBX). This is necessary because many 
larger offices may have more than one type of telephone network: one 
network may be dedicated to serving only internal office communications 
while another handles the external communications. In such a case, it 
becomes necessary to distinguish which line(s) should be used for internal 
communications and which should be used for external communications. 

The keyword used in the Class field of the Devices file is matched 
against the fourth field of Systems file entries as follows: 

Devices: ACU ttyli - D1200 penril 

Systems: eagle Any ACU D1200 ogin: nuucp \ ssword: Oakgrass 



Some devices can be used at any speed, so the keyword Any may be 
used in the Class field. If Any is used, the line will match any speed 
requested in a Systems file entry. If this field is Any and the Systems 
file Class field is Any, the speed defaults to 1200 bps. 

Dia ler- Token-Pairs 

This field contains pairs of dialers and tokens. The dialer portion may be 
the name of an automatic dial modem, a LAN switch, or it may be 
direct for a Direct Link device. You can have any number of 
dialer-token-pairs. The token portion may be supplied immediately 
following the dialer portion or if not present, it will be taken from a 
related entry in the Systems file. 

This field has the format: 



dialer token dialer token 

where the last pair may or may not be present, depending on the 
associated device (dialer). In most cases, the last pair contains only a 
dialer portion and the token portion is retrieved from the Phone field of 
the Systems file entry. 
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A valid entry in the dialer portion may be defined in the Dialers file or 
may be one of several special dialer types. The following special dialer 
types are compiled into the software and are therefore available without 
having entries in the Dialers file: 

801 — Bell 801 auto dialer 

TLI — Transport Level Interface Network (without STREAMS) 

TLIS — Transport Level Interface Network (with STREAMS) 

The Dialer-Token- Pairs (DTP) field may be structured in the following 
four ways, depending on the device associated with the entry: 

1. If an automatic dialing modem is connected directly to a port on your 
computer, the DTP field of the associated Devices file entry will only 
have one pair. This pair would normally be the name of the modem. 
This name is used to match the particular Devices file entry with an 
entry in the Dialers file. Therefore, the dialer field must match the first 
field of a Dialers file entry as shown below: 

Devices: ACU ttyll - 1200 ventel 

Dialers: ventel =&-% " " \r\p\r\c $ <K\T%%\r>\c ONLINE! 

Notice that only the dialer portion (ventel) is present in the DTP field of 
the Devices file entry. This means that the token to be passed on to the 
dialer (in this case the phone number) is taken from the Phone field of a 
Systems file entry. (\T is implied, see below.) Backslash sequences are 
described below. 

2. If a direct link is established to a particular computer, the DTP field of 
the associated entry would contain the keyword direct. This is true for 
both types of direct link entries, Direct and System-Name (refer to 
discussion on the Type field) . 

3. If a computer with which you wish to communicate is on the same local 
network switch as your computer, your computer must first access the 
switch and the switch can make the connection to the other computer. 
In this type of entry, there is only one pair. The dialer portion is used to 
match a Dialers file entry as shown below: 

Devices: develcon ttyl3 - 1200 develcon \D 

Dialers: develcon "" "" \pr\ps\c est:\007 \E\D\e \007 

As shown, the token portion is left blank, which indicates that it is 
retrieved from the Systems file. The Systems file entry for this 
particular computer will contain the token in the Phone field, which is 
normally reserved for the phone number of the computer (refer to 
Systems file, Phone field). This type of DTP contains an escape 
character ( \D) , which ensures that the contents of the Phone field will 
not be interpreted as a valid entry in the Dialcodes file. 
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4. If an automatic dialing modem is connected to a switch, your computer 
must first access the switch and the switch will make the connection to 
the automatic dialing modem. This type of entry requires two 
dialer-token-pairs. The dialer portion of each pair (fifth and seventh 
fields of entry) will be used to match entries in the Dialers file as shown 
below: 

Devices: ACU ttyl4 - 1200 develcon vent ventel 

Dialers: develcon 11 " "" \pr\ps\c est:\007 \E\D\e \007 

Dialers: ventel =&-% "" \r\p\r\c $ <K\T%%\r>\c ONLINE! 

In the first pair, develcon is the dialer and vent is the token that is 
passed to the Develcon switch to tell it which device (ventel modem) to 
connect to your computer. This token would be unique for each LAN 
switch since each switch may be set up differently. Once the ventel 
modem has been connected, the second pair is accessed, where ventel 
is the dialer and the token is retrieved from the Systems file. 

There are two escape characters that may appear in a DTP field: 

\T Indicates that the Phone (token) field should be translated 

using the Dialcodes file. This escape character is normally 
placed in the Dialers file for each caller script associated with 
an automatic dial modem (penril, ventel, etc.). Therefore, 
the translation will not take place until the caller script is 
accessed. 

\D Indicates that the Phone (token) field should not be 

translated usingthe Dialcodes file. If no escape character is 
specified at the end of a Devices entry, the \D is assumed 
(default). A \D is also used in the Dialers file with entries 
associated with network switches (develcon and micom). 



Protocols 

You can define the protocol to use with each device. In most cases it is not needed since 
you can use the default or define the protocol with the particular system you are calling 
(see Systems file, Type field). If you do specify the protocol, you must do in the form 
Type, Protocol. Currently, the only available protocol is 



g This protocol is slower and more reliable than e. It is good for 

transmission over noisy telephone lines. 



7.4.2 Dialers File 

The Dialers file (/usr/lib/uucp/Dialers) specifies the initial conversation that must take 
place on a line before it can be made available for transferring data. This conversation is 
usually a sequence of ASCII strings that is transmitted and expected, and it is often used 
to dial a phone number using an ASCII dialer (such as the Automatic Dial Modem). 
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As shown previously, the fifth field in a Devices file entry is an index into the Dialers file 
or a special dialer type (801, TLI, or TLIS). Here an attempt is made to match the fifth 
field in the Devices file with the first field of each Dialers file entry. In addition, each 
odd numbered Devices field starting with the seventh position is used as an index into the 
Dialers file. If the match succeeds, the Dialers entry is interpreted to perform the dialer 
negotiations. Each entry in the Dialers file has the following format: 

dialer substitutions expect-send . . . 

The Dialer field matches the fifth and additional odd numbered fields in the Devices file. 
The Substitutions field is a translate string: the first of each pair of characters is mapped 
to the second character in the pair. This is usually used to translate the equal sign (=) and 
the dash (-) into whatever the dialer requires for ’’wait for dialtone” and "pause.” 

The remaining expect-send fields are character strings. Below are some character strings 
distributed with the Basic Networking Utilities in the Dialers file: 

penril =W-P "" \d > s\p9\c) -W\p\r\ds\9\c-) y\c : \E\TP > 9\c OK 
ventel =&-% "" \r\p\r\c $ <K\T%%\r>\c ONLINE! 
hayes =,-, "" \dAT\r\c OK\r \EATDT\T\r\c CONNECT 

rixon =&-% "" \d\r\r\c $ s9\c)-W\r\ds9\c-) s\c : \T\r\c $ 9\c LINE 
vadiac =K-K "" \005\p *-\005\p-*\005\p-* D\p BER? \E\T\e \r\c LINE 
develcon "" 11 " \pr\ps\c est:\007 \E\D\e \007 
micom ,,,, "" \s\c NAME? \D\r\c GO 
direct 

att2212c =+-, "" \r\c : — : atol2=y ,T\T\r\c red 

att4000 =,-, "" \033\r\r\c DEM: \033s0401\c \006 \033s0901\c \ 

\006 \033sl001\c \006 \033sll02\c \006 \033dT\T\r\c \006 
att2224 =+-, "" \r\c : — : T\T\r\c red 
nls "" ,,M NLPS : 000 : 001 : l\N\c 

There are also three AT&T modems that have entries in the Dialers file. The meaning of 
some of the escape characters (those beginning with “\”) used in the Dialers file are listed 
below: 



\p Pause (approximately 12 to 14 seconds). 

\d Delay (approximately 2 seconds). 

\D Phone number or token without Dialcodes translation. 

\T ^hone number or token with Dialcodes translation. 

\K Insert a BREAK. 

\E Enable echo checking (for slow devices). 

\e Disable echo checking. 
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\r 


Carriage return. 


\c 


No newline or carriage return. 


\n 


Send newline. 


\nnn 


Send octal number. 



Additional escape characters that may be used are listed in the section discussing the 
Systems file. 

The penril entry in the Dialers file is executed as follows. First, the phone number 
argument is translated, replacing any “=” with a W (wait for dialtone) and replacing any 
with a P (pause). The handshake given by the remainder of the line works as follows: 



” ” Wait for nothing. (In other words, proceed to the next thing.) 

\d Delay for 2 seconds. 

> Wait for a greater than symbol (>). 

s\p9\c Send an “s”, pause for 1/2 second, send a “9”, send no terminating 

newline. 

)-W\p\r\ds\p9\c-) 

Wait for a “ )” character. If it is not received, process the string between 
the characters as follows. Send a “W”, pause, send a 
carriage-return, delay, send an “s”, pause, send a “9”, without a 
newline, and then wait for the “ )” character. 

y\c Send a “y”- 

: Wait for a colon (:). 

\E\TP Enable echo checking. (From this point on, whenever a character is 

transmitted, it will wait for the character to be received before doing 
anything else.) Then, send the phone number. The \T means take the 
phone number passed as an argument and apply the Dialcodes translation 
and the modem function translation specified by field 2 of this entry. 
Then send a “P”. 

> Wait for a greater-than sign (>). 

9\c Send a “9” without a newline. 

OK Waiting for the string “OK”. 
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7.4.3 Systems File 



The Systems file (/usr/lib/uucp/Systems) contains the information needed by the uucico 
daemon to establish a communication link to a remote computer. Each entry in the file 
represents a computer that can be called by your computer. In addition, the basic 
networking software can be configured to prevent any computer that does not appear in 
this file from logging in on your computer. More than one entry may be present for a 
particular computer. The additional entries represent alternative communication paths that 
will be tried in sequential order. 

Using the Sysfiles, you can define several files to be used as “Systems” files. See 
Subsection 7.4.8 for details. Each entry in the Systems file has the following format: 

System-Name Time Type Class Phone Login 
Each of these fields is defined below. 



System-name This field contains the node name of the remote computer. 

Time This field is a string that indicates the day and time when the remote 

computer can be called. The format of the Time field is: 

daytime [;retry ] 

The day portion may be a list containing: 

Su Mo Tu We Th Fr Sa for individual days 
Wk For any weekday (Mo Tu We Th Fr) 

Any For any day 

Never For a passive arrangement with the remote computer. If the 

Time field is Never, your computer will never initiate a call to 
the remote computer. The call must be initiated by the 
remote computer. In other words, your computer is in a 
passive mode in respect to the remote computer (see 
Subsection 7.4.5 for a discussion of the Permissions file). 

The time portion should be a range of times such as 0800-1230. If no 
time portion is specified, any time of day is assumed to be allowed for 
the call. A time range that spans 0000 is permitted. For example, 
0800-0600 means all times are allowed other than times between 6 a.m. 
and 8 a.m. 

Here is an example: 

Wk 1700-0800, Sa, Su 
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This example allows calls from 5:00 p.m. to 8:00 a.m., Monday through 
Thursday, and calls any time Saturday and Sunday. The example would 
be an effective way to call only when phone rates are low, if immediate 
transfer is not critical. 

An optional subfield, retry, is available to specify the minimum time (in 
minutes) before a retry, following a failed attempt. The default wait is 60 
minutes. The subfield separator is a semicolon (;). For example, Any;9 is 
interpreted as call any time, but wait at least 9 minutes before retrying 
after a failure occurs. 

Type This field contains the device type that should be used to establish the 

communication link to the remote computer. The keyword used in this 
field is matched against the first field of Devices file entries as shown 
below: 

Systems: eagle Any ACU.g dl200 3251 ogin:nuucp \ 

Devices: ACU ttyll - dl200 penril 

You can define the protocol used to contact the system by adding it on to 
the Type field. The example above shows how to attach the protocol g to 
the device type ACU. See the information under the “Protocols” section 
in the description of the Devices file for details. 

Class This field is used to indicate the transfer speed of the device used in 

establishing the communication link. It may contain a letter and speed 
(for example, C1200, D1200) to differentiate between classes of dialers 
(refer to the discussion on the Devices file, Class field). Some devices 
can be used at any speed, so the keyword Any may be used. This field 
must match the Class field in the associated Devices file entry as shown 
below: 

Systems: eagle Any ACU D1200 NY3251 ogin: nuucp \ 

ssword: Oakgrass 

Devices: ACU ttyll - D1200 penril 

If information is not required for this field, use a dash (-) as a place 
holder for the field. 

Phone This field is used to provide the phone number (token) of the remote 

computer for automatic dialers (LAN switches). The phone number is 
made up of an optional alphabetic abbreviation and a numeric part. If an 
abbreviation is used, it must be one that is listed in the Dialcodes file. 

For example: 
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Login 



Systems: eagle Any ACU D1200 NY3251 ogin: nuucp \ 

assword: Oakgrass 

Dialcodes: NY 9=1212555 

In this string, an equal sign (=) tells the ACU to wait for a secondary dial 
tone before dialing the remaining digits. A dash (-) in the string instructs 
the ACU to pause 4 seconds before dialing the next digit. 

If your computer is connected to a LAN switch, you may access other 
computers that are connected to that switch. The Systems file entries for. 
these computers will not have a phone number in the Phone field. 

Instead, this field will contain the token that must be passed on to the 
switch so it will know which computer your computer wishes to 
communicate with. (This is usually just the system name.) The associated 
Devices file entry should have a \D at the end of the entry to ensure 
that this field is not translated using the Dialcodes file. 

This field contains log-in information given as a series of fields and 
subfields of the format: 

expect send 

where expect is the string that is received and send is the string that is 
sent when the expect string is received. 

The expect field may be made up of subfields of the form: 

expect [-send-expect /... 

where the send is sent if the prior expect is not successfully read and the 
expect following the send is the next expected string. For example, with 
login — login , uucp will expect login. If uucp gets login, it will go on to 
the next field. If it does not get login, it will send nothing followed by a 
newline, then look for login again. If no characters are initially expected 
from the remote computer, the characters ” ” (null string) should be used 
in the first expect field. Note that all send fields will be sent followed by 
a newline unless the send string is terminated with a \c. 

Here is an example of a Systems file entry that uses an expect-send 
string: 

owl Any ACU 1200 Chicago6013 " " \r ogin : -BREAK— ogin : \ 
uucpx word: xyzzy 

This example says send a carriage return and wait for ogin: (for Login:). 
If you don’t get ogin:, send a BREAK. When you do get ogin: send the 
log-in name uucpx, then when you get word: (for Password:), send the 
password xyzzy. 
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There are several escape characters that cause specific actions when they 
are a part of a string sent during the log-in sequence. 



The following escape characters are useful in uucp communications: 

\N Send or expect a null character (ASCII NUL). 

\b Send or expect a backspace character. 

\c If at the end of a string, suppress the new line that is normally 

sent. Ignored otherwise. 

\d Delay 2 seconds before sending or reading more characters. 

\p Pause for approximately 12 to 14 seconds. 

\E Start echo checking. (From this point on, whenever a 

character is transmitted, it will wait for the character to be 
received before doing anything else.) 

\e Echo check off. 

\n Send a newline character. 

\r Send or expect a carriage return. 

\s Send or expect a space character. 

\t Send or expect a tab character. 

\\ Send or expect a backslash (\) character. 

EOT Send or expect EOT newline twice. 

BREAK Send or expect a break character. 

\K Same as BREAK. 

\ddd Collapse the octal digits (ddd) into a single character. 



Some versions of uucp, including the SR9.7 Domain/IX™ version, send 
the log-in sequence with even parity by default. The SR10 log-in 
program expects no parity. To change the parity of the log-in sequence 
sent, add the expect/send sequence of ”” P__ZERO before the log-in 
expect/send sequence in the L.sys file, for example. 



7.4.4 Dialcodes File 

The Dialcodes file (/usr/lib/uucp/Dialcodes) contains the dial-code abbreviations that can 
be used in the Phone field of the Systems file. Each entry has the format: 

abb dial-seq 

where abb is the abbreviation used in the Systems file Phone field and dial-seq is the dial 
sequence that is passed to the dialer when that particular Systems file entry is accessed. 
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The entry 



jt 9-847 

would be set up to work with a Phone field in the Systems file such as jt7867. When the 
entry containing jt7867 is encountered, the sequence 9=847-7867 would be sent to the 
dialer if the token in the dialer-token-pair is \T. 



7.4,5 Permissions File 

The Permissions file (/usr/lib/uucp/Permissions) specifies the permissions that remote 
computers have with respect to login, file access, and command execution. There are 
options that restrict the remote computer’s ability to request files and its ability to receive 
files queued by the local site. Another option is available that specifies the commands that 
a remote site can execute on the local computer. 



How Entries are Structured 

Each entry is a logical line with physical lines terminated by a backslash (\)to indicate 
continuation. Entries are made up of options delimited by white space. Each option is a 
name/value pair in the following format: 

name-value 

Note that no white space is allowed within an option assignment. 

Comment lines begin with a pound sign (#) and they occupy the entire line up to a 
newline character. Blank lines are ignored (even within multiline entries). 

There are two types of Permissions file entries: 

® LOGNAME — Specifies the permissions that take effect when a remote computer 
logs in on (calls) your computer. 

® MACHINE — Specifies permissions that take effect when your computer logs in 
on (calls) a remote computer. 
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Considerations 

The following items should be considered when using the Permissions file to restrict the 
level of access granted to remote computers: 

® All log-in IDs used by remote computers to log in for uucp communications must 
appear in one and only one LOGNAME entry. 

® Any site that is called whose name does not appear in a MACHINE entry will 
have the following default permissions/restrictions: 

— Local send and receive requests will be executed. 

— The remote computer can send files to your computer's 
/usr/spool/uucppublic directory. 

— The commands sent by the remote computer for execution on your 
computer must be one of the default commands, usually rmail. 



Options 

This subsection describes each option, tells how it is used, and lists its default values. 



REQUEST When a remote computer calls your computer and requests to receive a 
file, this request can be granted or denied. The REQUEST option 
specifies whether the remote computer can request to set up file transfers 
from your computer. 

REQUEST=yes 

Specifies that the remote computer can request to transfer 
files from your computer. 

REQUEST=no 

specifies that the remote computer cannot request to receive 
files fromyour computer. This is the default value. It will be 
used if the REQUEST option is not specified. The REQUEST 
option can appear in either a LOGNAME (remote calls you) 
entry or a MACHINE (you call remote) entry. A note on 
security: When a remote machine calls you, unless you have a 
unique login and password for that machine you don't know if 
the machine is who it says it is. 

SENDFILES When a remote computer calls your computer and completes its work, it 
may attempt to take work your computer has queued for it. The 
SENDFILES option specifies whether your computer can send the work 
queued for the remote computer. 
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The string 
SENDFILES=yes 

specifies that your computer may send the work that is queued for the 
remote computer as long as it logged in as one of the names in the 
LOGNAME option. This string is mandatory if your computer is in a 
“passive mode” with respect to the remote computer. 

The string 

SENDFILES=call 

specifies that files queued in your computer will be sent only when your 
computer calls the remote computer. The call value is the default for the 
SENDFILE option. This option is only significant in LOGNAME entries 
since MACHINE entries apply when calls are made out to remote 
computers. If the option is used with a MACHINE entry, it will be 
ignored. 

READ and WRITE 

These options specify the various parts of the file system that uucico can 
read from or write to. The READ and WRITE options can be used with 
either MACHINE or LOGNAME entries. 

The default for both the READ and WRITE options is the uucppublic 
directory as shown in the following strings: 

READ=/usr/spool/uucppublic 

WRITE=/usr/spool/uucppublic 

The strings 

READ=/ WRITE=/ 

specify permission to access any file that can be accessed by a local user 
with “other” permissions. 

The value of these entries is a colon separated list of pathnames. The 
READ option is for requesting files, and the WRITE option for depositing 
files. One of the values must be the prefix of any full pathname of a file 
coming in or going out. To grant permission to deposit files in /usr/news 
as well as the public directory, the following values would be used with 
the WRITE option: 

WRITE=/usr/spool/uucppublic : /usr/news 
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It should be pointed out that if the READ and WRITE options are used, 
all pathnames must be specified because the pathnames are not added to 
the default list. For instance, if the /usr/news pathname was the only one 
specified in a WRITE option, permission to deposit files in the public 
directory would be denied. 

You should be careful what directories you make accessible for reading 
and writing by remote systems. For example, you probably wouldn’t want 
remote computers to be able to write over your /etc/passwd file so /etc 
shouldn’t be open to writes. 

NOREAD and NOWRITE 

The NOREAD and NOWRITE options specify exceptions to the READ 
and WRITE options or defaults. The strings: 

READ=/ NOREAD=/etc WRITE=/usr/spool/uucppublic 

would permit reading any file except those in the /etc directory (and its 
subdirectories) and writing only to the default /usr/spool/uucppublic 
directory. NOWRITE works in the same manner as the NOREAD option. 
The NOREAD and NOWRITE can be used in both LOGNAME and 
MACHINE entries. 

CALLBACK The CALLBACK option is used in LOGNAME entries to specify that no 
transaction will take place until the calling system is called back. There 
are two examples of when you would use CALLBACK. From a security 
standpoint, if you call back a machine, you can be sure it is the machine 
it says it is. If you are doing long data transmissions, you can choose the 
machine that will be billed for the longer call. 

The string 
CALLB ACK=y e s 

specifies that your computer must call the remote computer back before 
any file transfers will take place. 

The default for the CALLBACK option is 

CALLBACK=no 

The CALLBACK option is very rarely used. Note that, if two sites have 
this option set for each other, a conversation will never get started. 
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COMMANDS 



The COMMANDS option can be hazardous to the security of your 
system. Use it with extreme care. 

The uux program will generate remote execution requests and queue 
them to be transferred to the remote computer. Files and a command are 
sent to the target computer for remote execution. The COMMANDS 
option can be used in MACHINE entries to specify the commands that a 
remote computer can execute on your computer. Note that COMMANDS 
is not used in a LOGNAME entry; COMMANDS in MACHINE entries 
define command permissions whether we call the remote system or it calls 
us. 



The string 
COMMANDS=rmai 1 

indicates the default commands that a remote computer can execute on 
your computer. If a command string is used in a MACHINE entry, the 
default commands are overridden. For instance, the entry: 

MACHINE=owl : raven : hawk : dove \ 

COMMANDS=rmai 1 : rnews : lp 

overrides the COMMAND default so that the computers owl, raven, 
hawk, and dove can now execute rmail, rnews, and lp on your 
computer. 

In addition to the names as specified above, there can be full pathnames 
of commands. For example, 

COMMANDS=rma i 1 : /usr/lbin/rnews : /usr/local/lp 

specifies that command rmail uses the default path. The default paths for 
your computer are /bin, /usr/bin, and /usr/lbin. When the remote 
computer specifies rnews or /usr/lbin/rnews for the command to be 
executed, /usr/lbin/rnews will be executed regardless of the default path. 
Likewise, /usr/local/lp is the lp command that will be executed. 

Including the ALL value in the list means that any command from the 
remote computer (s) specified in the entry will be executed. If you use 
this value, you give the remote computer full access to your computer. Be 
careful. This allows far more access than normal users have. 

The string 

COMMANDS=/usr/lbin/rnews : ALL : /usr/local/lp 
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VALIDATE 



illustrates two points: The ALL value can appear anywhere in the string, 
and the pathnames specified for rnews and lp will be used (instead of 
the default) if the requested command does not contain the full 
pathnames for rnews or lp. 

The VALIDATE option should be used with the COMMANDS option 
whenever potentially dangerous commands like cat and uucp are 
specified with the COMMANDS option. Any command that reads or 
writes files is potentially dangerous to local security when executed by the 
uucp remote execution daemon (uuxqt). 

The VALIDATE option is used in conjunction with the COMMANDS 
option when specifying commands that are potentially dangerous to your 
computer’s security. It is used to provide a certain degree of verification 
of the caller’s identity. The use of the VALIDATE option requires that 
privileged computers have a unique login/password for uucp transactions. 
An important aspect of this validation is that the login/password 
associated with this entry be protected. If an outsider gets that 
information, that particular VALIDATE option can no longer be 
considered secure. (VALIDATE is merely an added level of security on 
top of the COMMANDS option; although, it is a more secure way to 
open command access than ALL.) 

Careful consideration should be given to providing a remote computer 
with a privileged login and password for uucp transactions. Giving a 
remote computer a special login and password with file access and remote 
execution capability is like giving anyone on that computer a normal login 
and password on your computer. Therefore, if you cannot trust someone 
on the remote computer, do not provide that computer with a privileged 
login and password. 

The following LOGNAME entry 

LOGNAME=uuc p f r i end VALIDATE=eagle : owl : hawk 

specifies that if one of the remote computers that claims to be eagle, 
owl, or hawk logs in on your computer, it must have used the login 
uucpfriend. As can be seen, if an outsider gets the uucpfriend 
login/password, masquerading is trivial. 

But what does this have to do with the COMMANDS option, which only 
appears in MACHINE entries? It links the MACHINE entry (and 
COMMANDS option) with a LOGNAME entry associated with a 
privileged login. This link is needed because the execution daemon is not 
running while the remote computer is logged in. In fact, it is an 
asynchronous process with no knowledge of what computer sent the 
execution request. Therefore, the real question is how does your 
computer know where the execution files came from. 
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Each remote computer has its own “spool” directory on your Computer. 
These spool directories have write permission given only to the uucp 
programs. The execution files from the remote computer are put in its 
spool directory after being transferred to your computer. When the uuxqt 
daemon runs, it can use the spool directory name to find the MACHINE 
entry in the Permissions file and get the COMMANDS list; or, if the 
computer name does not appear in the Permissions file, the default list 
will be used. 

The following example shows the relationship between the MACHINE 
and LOGNAME entries: 

MACHINE=eagle: owl: hawk REQUEST=yes \ 

COMMANDS=rmail : /usr/lbin/rnews \ 

READ=/ WRITE=/ 



LOGNAME =uucpz VALIDATE=eagle : owl : hawk \ 
REQUEST=yes SENDFILES=yes \ 

READ=/ WRITE=/ 



The value in the COMMANDS option means that remote mail and 
/usr/lbin/rnews can be executed by remote users. 

In the first entry, you must make the assumption that when you want to 
call one of the computers listed, you are really calling either eagle, owl, 
or hawk. Therefore, any files put into one of the eagle, owl, or hawk 
spool directories is put there by one of those computers. If a remote 
computer logs in and says that it is one of these three computers, its 
execution files will also be put in the privileged spool directory. You 
therefore have to validate that the computer has the privileged login. 

You may want to specify different option values for the computers your 
computer calls that are not mentioned in specific MACHINE entries. This 
may occur when there are many computers calling in, and the command 
set changes from time to time. The name ” OTHER” for the computer 
name is used for this entry as shown below: 

MACHINE=OTHER \ 

COMMANDS=rma i 1 : rnews : /usr/lbin/Photo : /usr/lbin/xp 



All other options available for the MACHINE entry may also be set for 
the computers that are not mentioned in other MACHINE entries. 
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Combining MACHINE and LOGNAME Entries 

It is possible to combine MACHINE and LOGNAME entries into a single entry where the 
common options are the same. For example, the two entries: 

MACHINE=eagle: owl: hawk REQUEST=yes \ 

READ=/ WRITE=/ 

LOGNAME=uucpz REQUEST=yes SENDFILES=yes \ 

READ=/ WRITE=/ 

share the same REQUEST, READ, and WRITE options. These two entries can be merged 
as shown below: 

MACHINE=eagle : owl : hawk REQUEST=yes \ 

LOGNAME=uucpz SENDFILES=yes \ 

READ=/ WRITE=/ 



7.4.6 Poll File 

The Poll file (/usr/lib/uucp/Poll) contains information for polling remote computers. Each 
entry in the Poll file contains the name of a remote computer to call, followed by a 
<TAB> character (a space won’t work), and finally the hours the computer should be 
called. The format of entries in the Poll file are 

sys-name hour ... 

For example the entry: 

eagle 0 4 8 12 16 20 

will provide polling of computer eagle every four hours. 

The uudemon.poll script does not actually perform the poll. It merely sets up a polling 
work file (always named C./z7e), in the spool directory that will be seen by the scheduler, 
which is started by uudemon.hour. 



7.4.7 Devconfig File 

The /usr/lib/uucp/Devconfig file is used when your computer communicates over a 
STARLAN network or some other Streams-based transport provider that conforms to the 
AT&T Transport Interface (TI) . Note that uucp over TI is not supported with this 
release. 
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Devconfig entries define the STREAMS modules that are used for a particular TI device. 
Entries in the Devconfig file have the format: 

service- x device-y push-z [:z ... ] 

where x can be cu, uucico, or both separated by a colon; y is the name of a TI network 
and must match an entry in the Devices file; and z is replaced by the names of STREAMS 
modules in the order that they are to be pushed onto the Stream. Different modules and 
devices can be defined for cu and uucp services. 

The following entries should most commonly be used in the file: 

service=cu device=STARLAN push=ntty: tirdwr: ldO 
service=uucico device=STARLAN push=ntty: tirdwr: ldO 

This example pushes ntty then tirdwr, then ldO. 



7.4.8 Sysfiles File 

The /usr/lib/uucp/Sysfiles file lets you assign different files to be used by uucp and cu as 
Systems, Devices, and Dialers files. This optional file may be useful in the following 
cases: 

• You may want different Systems files so requests for log in services can be made 
to different addresses than uucp services. 

• You may want different Dialers files to use different handshaking for cu and 

uucp. 

• You may want to have multiple Systems, Dialers, and Devices files. The Systems 
file in particular may become large, making it more convenient to split it into 
several smaller files. 

The format of the Sysfiles file is: 

services systems=x:x dialers=y:y devices=z:z 

where w is replaced by uucico, cu, or both separated by a colon; x is one or more files to 
be used as the Systems file, with each file name separated by a colon and read in the 
order presented; y is one or more files to be used as the Dialers file; and z is one or more 
files to be used as the Devices file. Each file is assumed to be relative to the /usr/lib/uucp 
directory, unless a full path is given. A backslash-carriage return ( \<CR>) can be used to 
continue an entry on to the next line. 
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Here’s an example of using a local Systems file in addition to the usual Systems file: 



service=uucico : cu systems=Systems : Local_Systems 

If this is in /usr/lib/uucp/Sysfiles, then both uucico and cu will first look in 
/usr/lib/uucp/Systems. If the system they’re trying to call doesn’t have an entry in that 
file, or if the entries in the file fail, then they’ll look in /usr/lib/uucp/Local_Systems. 

When different Systems files are defined for uucico and cu services, your machine will 
store two different lists of Systems. You can print the uucico list using the uuname 
command or the cu list using the uuname -c command. 



7.5 Administration 

The role of the uucp administrator depends heavily on the amount of traffic that enters or 
leaves a system and the quality of the connections that can be made to and from that 
system. For the average system, only a modest amount of traffic (100 to 200 files per day) 
pass through the system and little if any intervention with the uucp automatic cleanup 
functions is necessary. Systems that pass large numbers of files (200 to 10.000) may 
require more attention when problems occur. 

The following subsections describe the routine administrative tasks that must be performed 
by the administrator or are automatically performed by the uucp package. A subsection on 
problems describes frequent problems and how to deal with them effectively. 



7,5.1 Cleanup 

The biggest problem in a dial-up network like uucp is dealing with the backlog of jobs that 
cannot be transmitted to other systems. The following clean-up activities should be 
routinely performed by shell scripts started from cron(l). 



Cleanup of Undeliverable Jobs 

The uudemon. cleanup script usually contains an invocation of the uucleanup command to 
purge any jobs that are older than some fixed time (usually 72 hours). It is also used to 
purge any lock or status files. An sample invocation of uucleanup (1M) to remove old 
work, data, and execute files follows: 

/usr/lib/uucp/uucleanup -c7 -d7 -x7 -w7 
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7.5.2 Polling Other Systems 



Systems that are passive members of the network must be polled by other systems in order 
for their files to be sent. To do this, set up the Poll file (/usr/lib/uucp/poll) with entries 
in the following format: 

sys-name hour . . . 

When the uudemon.poll script is run, it sets up the appropriate work files in the /spool 
directory. These will be seen and processed by the scheduler. 



7.5.3 Problems 

The following subsections list the most frequent problems that appear on systems that make 
heavy use of uucp. 



Out of Space 

The file system used to spool incoming or outgoing jobs can run out of space and prevent 
jobs from being spawned or received from remote systems. The inability to receive jobs is 
the worse of the two conditions. When file space does become available, the system will be 
flooded with the backlog of traffic. 



Bad ACU and Modems 

The ACU and incoming modems occasionally cause problems that make it difficult to 
contact other systems or to receive files. These problems are usually readily identifiable 
since files in the /.Log directory will usually have entries that point to the bad line. If a 
bad line is suspected, use the cu command to try calling another system using the 
suspected line. 



Administrative Problems 

Some uucp networks have so many members that it is difficult to keep track of changing 
passwords, changing phone numbers, or changing logins on remote systems. This can be a 
very costly problem since ACUs will be tied up calling a system that cannot be reached. 
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7.6 Debugging 



In order to verify that a system on the network can be contacted, the uucico daemon can 
be invoked directly from a user’s terminal directly. For example, to verify that mhtsd can 
be contacted, a job would be queued for that system as follows: 

uucp -r file mhtsd!~/tom 

The -r option forces the job to be queued but does not invoke the daemon to process the 
job. The uucico command can then be invoked directly: 

/usr/lib/uucp/uucico -rl -x4 -smhtsd 

The -rl option is necessary to indicate that the daemon is to start up in master mode 
(i.e., it is the calling system). The -x4 specifies the level of debugging that is to be 
printed. Higher levels of debugging can be printed (greater than 4) but require familiarity 
with the internals of uucico. 

If several jobs are queued for the remote system, it is not possible to force uucico to send 
one particular job first. 

The contents of the files in the //usr/spool/uucp/.Log directory should also be monitored 
for any error indications that are posted in that directory. Frequently, problems can be 
isolated by examining the entries in the file corresponding to a particular system. For 
example, to examine log files for a system named “apollo,” you would look at 
//usr/spool/uucp/.Log/uucp/apollo. This structure is illustrated in Figure 7-1. 
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Figure 7-1. Directory Structure 
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Routing mail through a heterogeneous internet presents many problems. Among the worst 
of these is that of address mapping. Historically, this has been handled on an ad hoc basis. 
However, this approach has become unmanageable as internets grow. 

The sendmail facility acts a unified “post office” to which all mail can be submitted. Ad- 
dress interpretation is controlled by a production system, which can parse both domain- 
based addressing and old-style ad hoc addresses. The production system is powerful 
enough to rewrite addresses in the message header to conform to the standards of a num- 
ber of common target networks, including old ARPANET, new ARPANET, uucp, and 
Phonenet. The sendmail facility also implements a Simple Mail Transfer Protocol (SMTP) 
server, message queueing, and aliasing. 



NOTE: This chapter is largely taken from the original Berkeley sendmail 

Installation and Operation Guide , and the paper Introduction to 
sendmail by Eric Allman. 



8.1 Introduction 

The sendmail facility implements a general internetwork mail routing facility, featuring 
aliasing and forwarding, automatic routing to network gateways, and flexible configuration. 

In a simple network, each node has an address, and resources can be identified with a 
host-resource pair; in particular, the mail system can refer to users using a host-name-us- 
er-name pair. Host names and numbers have to be administered by a central authority, 
but user names can be assigned locally to each host. 

In an internet, multiple networks with different characteristics and managements must com- 
municate. In particular, the syntax and semantics of resource identification change. Cer- 
tain special cases can be handled simply by ad hoc techniques, such as providing network 
names that appear local to hosts on other networks, as with the ETHERNET at Xerox- 
PARC. However, the general case is extremely complex. For example, some networks re- 
quire point-to-point routing, which simplifies the database update problem since only 
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adjacent hosts must be entered into the system tables, while others use end-to-end ad- 
dressing. Some networks use a left-associative syntax and others use a right-associative 
syntax, causing ambiguity in mixed addresses. 

The sendmail facility is intended to help bridge the gap between the totally ad hoc world 
of networks that know nothing of each other and the clean, tightly coupled world of 
unique network numbers. It can accept arbitrary address syntaxes and domain-based ad- 
dressing, resolving ambiguities by using heuristics specified by the system administrator. It 
helps guide the conversion of message formats between disparate networks. In short, 
sendmail is designed to assist a graceful transition to consistent internetwork addressing 
schemes. 



8.2 Interfaces to the Outside World 

There are three ways sendmail can communicate with the outside world, both in receiving 
and in sending mail. The sendmail utility communicates by using the conventional UNIX 
argument vector/return status, speaking SMTP over a pair of UNIX pipes, and speaking 
SMTP over an interprocess (or) channel. 

8.2.1 Argument Vector/Exit Status 

This technique is the standard UNIX method for communicating with the process. A list of 
recipients is sent in the argument vector, and the message body is sent on the standard 
input. Anything that the mailer prints is simply collected and sent back to the sender if 
there were any problems. The exit status from the mailer is collected after the message is 
sent, and a diagnostic is printed if appropriate. 

8.2.2 SMTP Over Pipes 

The SMTP protocol can be used to run an interactive lock-step interface with the mailer. 
A subprocess is still created, but no recipient addresses are passed to the mailer via the 
argument list. Instead, they are passed one at a time in commands sent to the processes 
standard input. Anything appearing on the standard output must be a reply code in a spe- 
cial format. 

8.2.3 SMTP Over an IPC Connection 

This technique is similar to the previous technique, except that it uses an IPC channel. 

This method is exceptionally flexible in that the mailer need not reside on the same ma- 
chine. It is normally used to connect to a sendmail process on another machine. 



8.3 Configuration 

Almost all configuration information is read at run time from an ASCII file: encoding 
macro definitions (the value of macros used internally), header declarations (the format of 
header lines that sendmail will process specially,) mailer definitions (information such as 
the location and characteristics of each mailer) , and address rewriting rules (a limited pro- 
duction system to rewrite addresses which used to parse and rewrite the addresses) . 
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Configuration is controlled primarily by a configuration file read at startup. If the mail is 
being sent by a local user, and the file “.mailcf” exists in the sender’s home directory, that 
file is read as a configuration file after the system configuration file. The primary use of 
this feature is to add header lines. 

The configuration file encodes macro definitions, header definitions, mailer definitions, re- 
writing rules, and options. Refer to Section 8.8 for details on the configuration file. 



Macros 

Macros can be used in three ways. Certain macros transmit unstructured textual informa- 
tion into the mail system, such as the name sendmail will use to identify itself in error 
messages. Other macros transmit information from sendmail to the configuration file for 
use in creating other fields (such as argument vectors to mailers); for example, the name 
of the sender, and the host and user of the recipient. Other macros are unused internally, 
and can be used as shorthand in the configuration file. 



Header Declarations 

Header declarations inform sendmail of the format of known header lines. Knowledge of a 
few header lines is built into sendmail, such as the “From:” and “Date:” lines. 

Most configured headers will be automatically inserted in the outgoing message if they 
don’t exist in the incoming message. Certain headers are suppressed by some mailers. 



Mailer Declarations 

Mailer declarations tell sendmail of the various mailers available to it. The definition speci- 
fies the internal name of the mailer, the pathname of the program to call, some flags asso- 
ciated with the mailer, and an argument vector to be used on the call; this vector is mac- 
ro-expanded before use. 



Address Rewriting Rules 

The configuration file supports the editing of addresses into different formats. For example, 
an address of the form: 

ucsfcglltef 

might be mapped into the following to conform to the Domain/OS syntax: 
tef@ucsfcgl. uucp 

Translations can also be done in the other direction. 



8.4 Installation 

Due to the requirements of flexibility for sendmail, the configuration file can seem some- 
what unapproachable. However, there are only a few basic configurations for most sites, for 
which standard configuration files have been supplied. Note that Apollo’s pre-installed soft- 
ware enables both SysV and Berkeley mailers to use sendmail as is. 
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The remainder of this chapter assumes that you can use one of the existing configurations 
and that the standard installation parameters are acceptable. All pathnames and examples 
are given from the root of the sendmail subtree. 

8.4,1 Off-the-Shelf Configurations 

Apollo UNIX environments are supplied with three sample configuration files. These files 
are extensively commented and can work “as is” for many sites. 

• /usr/lib/uucpproto. cf 

• /usr/lib/arpaproto. cf 

• /usr/lib/sendmail . cf 

These off-the-shelf configuration files are supplied to handle the basic cases: 
/usr/lib/arpaproto. cf for ARPANET (TCP) sites and /usr/lib/uucpproto. cf for uucp sites. 
To install uucpproto.cf as your configuration, for example, you could use the following 
commands: 



$ cd /usr/lib 

$ cp uucpproto.cf sendmail. cf 

The off-the-shelf configuration files will get you started with sendmail. However, you can 
have to adjust the configuration file to meet the needs of your particular mail delivery sys- 
tem. 



8.5 sendmail Arguments, Configuration Options, and Mailer Flags 

The sendmail command, /usr/lib/sendmail, provides a set of arguments and options that 
enable you to specify the kind of processing you want. This section describes the argu- 
ments and options in detail. Arguments must be presented with flags before addresses. 
The flags are 



-f addr The sender’s machine address is addr. This flag is ignored unless the real 

user is listed as a “trusted user” or if addr contains an exclamation point 
(because of certain restrictions in uucp). 

-r addr An obsolete form of -f. 



-h cnt Sets the “hop count” to cnt. This represents the number of times this 

message has been processed by sendmail (to the extent that it is sup- 
ported by the underlying networks) .The cnt is incremented during proc- 
essing, and if it reaches MAXHOP (currently 30) sendmail throws away 
the message with an error. 

-F name Sets the full name of this user to name. 
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Don’t do aliasing or forwarding. 



-n 

-t Read the header for “To:”, “Cc:”, and “Bcc:” lines, and send to every- 

one listed in those lists. The “Bcc:” line will be deleted before sending. 
Any addresses in the argument vector will be deleted from the send list. 

-b* Set operation mode to x. Operation modes are 

m Deliver mail (default) 

a Run in arpanet mode (see below) 

s Speak SMTP on input side 

d Run as a daemon 

t Run in test mode 

v Just verify addresses, don’t collect or deliver 

i Initialize the alias database 

p Print the mail queue 

z Freeze the configuration file (Not currently supported) 

The special processing for the ARPANET includes reading the “From:” line from the 
header to find the sender, printing ARPANET style messages (preceded by three-digit re- 
ply codes for compatibility with the FTP protocol), and ending lines of error messages with 
<CRLF>. 

-q time 



-C file 
-d level 
-o xvalue 



Try to process the queued up mail. If the time is given, a sendmail will 
run through the queue at the specified interval to deliver queued mail; 
otherwise, it only runs once. 

Use a different configuration file. 

Set debugging level. 

Set option x to the specified value. These options are described in the 
below. 



Configuration Options 

The following options can be set using the -o flag on the command line or the O line in 
the configuration file: 



A file Use the named file as the alias file. If no file is specified, use aliases in 

the current directory. 

a If set, wait for an “@:@” entry to exist in the alias database before start- 

ing up. If it does not appear in five minutes, rebuild the database. 

c If an outgoing mailer is marked as being expensive, don’t connect imme- 

diately. This requires that queueing be compiled in, since it will depend 
on a queue run process to actually send the mail. 

dx Deliver in mode x. Legal modes are 

i Deliver interactively (synchronously) 

b Deliver in background (asynchronously) 

q Just queue the message (deliver during queue run) 
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If set, rebuild the alias database if necessary and possible. If this option is 
not set, sendmail will never rebuild the alias database unless explicitly 
requested using -bi. 

Dispose of errors using mode x. The values for x are: 

p Print error messages (default) 

q No messages, just give exit status 

m Mail back errors 

w Write back errors (mail if user not logged in) 

e Mail back errors and give 0 exit stat always 

The temporary file mode, in octal. 644 and 600 are good choices. 

S^ve the UNIX system “From” lines at the front of headers. Normally 
they are assumed redundant and discarded. 

Set the default group ID for mailers to run in to n. 

Specify the help file for SMTP. 

Ignore dots in incoming messages. 

Set the default log level to n. 

Set the macro x to value. This is intended only for use from the com- 
mand line. 

Send to me too, even if I am in an alias expansion. 

Assume that the headers contain spaces to delimit names. This actually 
turns on an adaptive algorithm: if any recipient address contains a 
comma, parenthesis, or angle bracket, it will be assumed that commas 
already exist. If this flag is not on, only commas delimit names. Headers 
are always output with commas between the names. 

Use the named dir as the queue directory. 

Timeout reads after time interval. 

Log statistics in the named file. 

Always instantiate the queue file, even if you are going to attempt imme- 
diate delivery, sendmail always instantiates the queue file before returning 
control the the client under any circumstances. 

Set the queue timeout to time. After this interval, messages that have not 
been successfully sent will be returned to the sender. 

Set the local timezone name to S for standard time and D for daylight 
time; this is only used under version six. 

Set the default userid for mailers to n. Mailers without the S flag in the 
mailer definition will run as this user. 
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y 



Run in verbose mode. 



Mailer Description Flags 

There are a number of options that can be specified as primitive flags (provided for com- 
patibility with delivermail). These are the e, i, m, and v options. Also, the f option can 
be specified as the -s flag. 

The following flags can be set in the mailer description. 



f The mailer wants a -f from flag, but only if this is a network forward op- 

eration (that is, the mailer will give an error if the executing user does 
not have special permissions) . 

r Same as f, but sends a -r flag. 

S Don’t reset the user ID before calling the mailer. This would be used in a 

secure environment where sendmail ran as root. This could be used to 
avoid forged addresses. This flag is suppressed if given from an “unsafe” 
environment (for example, a user’s mail.cf file). 

n Do not insert a UNIX system “From” line on the front of the message. 

1 This mailer is local (that is, final delivery will be performed). 

s Strip quote characters off of the address before calling the mailer. 

m This mailer can send to multiple users on the same host in one transac- 

tion. When a $u macro occurs in the argv part of the mailer definition, 
that field will be repeated as necessary for all qualifying users. 

F This mailer wants a “From:” header line. 

D This mailer wants a “Date:” header line. 

M This mailer wants a “Message-id:” header line. 

x This mailer wants a “Full-Name:” header line. 

P This mailer wants a “Return-Path:” line. 

u Uppercase should be preserved in user names for this mailer. 

h Uppercase should be preserved in host names for this mailer. 

A This is an ARPANET-compatible mailer, and all appropriate modes 

should be set. 

U • This mailer wants UNIX system “from” lines with the uucp-style “remote 

from <host>” on the end. 

e This mailer is expensive to connect to, so try to avoid connecting nor- 

mally; any necessary connection will occur during a queue run. 
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X This mailer want to use the hidden dot algorithm as specified in RFC821; 

basically, any line beginning with a dot will have an extra dot prepended 
(to be stripped at the other end). This ensures that lines in the message 
containing a dot will not terminate the message prematurely. 

L Limit the line lengths as specified in RFC821. 

P Use the return-path in the SMTP “MAIL FROM:” command rather than 

just the return address. 

I This mailer will be speaking SMTP to another sendmail — as such, it can 

use special protocol features. This option is not required (that is, if this 
option is omitted the transmission will still operate successfully, although 
perhaps not as efficiently as possible). 

C If mail is received from a mailer with this flag set, any addresses in the 

header that do not have an at sign (“@”) after being rewritten by rule set 
three will have the “©domain” clause from the sender tacked on. This 
allows mail with headers of the form: 

From: usera@hosta 
To: userb@hostb, userc 

to be automatically rewritten as: 

From: usera@hosta 

To: userb@hostb, userc@hosta 



For your convenience, refer to online sendmail manual pages (1M) for detailed descrip- 
tions of the options and flags that Apollo provides. 



8.6 Normal Operation 

8.6.1 The System Log 

The system log is supported by the syslog(8) program. 

Each line in the system log consists of a time stamp, the name of the machine that gener- 
ated it (for logging from several machines over the ETHERNET), the word “sendmail:”, 
and a message. 



Levels 

If you have syslog(8) or an equivalent installed, you will be able to do logging. There is a 
large amount of information that can be logged. The log is arranged as a succession of lev- 
els. At the lowest level, only extremely strange situations are logged. At the highest level, 
even the most mundane events are recorded. As a convention, log levels under 10 are 
considered “useful;” log levels above 10 are usually for debugging purposes. 
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8.6.2 The Mail Queue 



The mail queue should be processed transparently. However, you can find that manual 
intervention is sometimes necessary. For example, if a major host is down for a period of 
time the queue can become clogged. Although sendmail ought to recover gracefully when 
the host comes up, you can find performance unacceptably bad in the meantime. 



Printing the Queue 

The contents of the queue can be printed by using the mailq command (or by specifying 
the -bp flag to sendmail): 



The mailq Command 

This will produce a listing of the queue IDs, the size of the message, the date the message 
entered the queue, and the sender and recipients. 



Format of Queue Files 

All queue files have the form xfAA99999 where AA99999 is the ID for this file and the x 
is a type. The types are 



d The data file. The message body (excluding the header) is kept in this 

file. 

1 The lock file. If this file exists, the job is currently being processed, and 

a queue run will not process the file. For that reason, an extraneous If 
file can cause a job to apparently disappear. 

n This file is created when an ID is being created. It is a separate file to 

ensure that no mail can ever be destroyed due to a race condition. It 
should exist for no more than a few milliseconds at any given time. 

q The queue control file. This file contains the information necessary to 

process the job. 

t A temporary file. These are an image of the qf file when it is being re- 

built. It should be renamed to a qf file very quickly. 

x A transcript file, existing during the life of a session showing everything 

that happens during that session. 



The qf file is structured as a series of lines each beginning with a code letter. The lines are 
as follows: 



D The name of the data file. There can only be one of these lines. 

H A header definition. There can be any number of these lines. The order 

is important; they represent the order in the final message. These use the 
same syntax as header definitions in the configuration file. 
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R A recipient address. This will normally be completely aliased, but is actu- 

ally realiased when the job is processed. There will be one line for each 
recipient. 

S The sender address. There can only be one of these lines. 

T The job creation time. This is used to compute when to time out the job. 

P The current message priority. This is used to order the queue. Higher 

numbers mean lower priorities. The priority increases as the message sits 
in the queue. The initial priority depends on the message class and the 
size of the message. 

M A message. This line is printed by the mailq command, and is generally 

used to store status information. It can contain any text. 



As an example, the following is a queue file sent to “mckusick@calder” and “wnj”: 

Ddf A13557 
Seric 

T404261372 

P132 

Rmckus ick@calder 
Rwnj 

H?D?date: 23-Oct-82 15:49:32-PDT (Sat) 

H?F?from: eric (Eric Allman) 

H?x? full-name: Eric Allman 
Hsubject: this is an example message 

Hmessage-id: <8209232249. 13557@UCBARPA. BERKELEY. ARPA> 

Hreceived: by UCBARPA . BERKELEY . ARPA (3.227 [10/22/82]) id A13557; 
23-Oct-82 15:49: 32-PDT (Sat) 

Hphone : (415) 548-3211 

HTo : mckusick@calder, wnj 

This shows the name of the data file, the person who sent the message, the submission 
time (in seconds since January 1, 1970), the message priority, the message class, the re- 
cipients, and the headers for the message. 



Forcing the Queue 

In some cases, you may find that a major host going down for a couple of days can create 
a prohibitively large queue. This will result in sendmail spending an inordinate amount of 
time sorting the queue. This situation can be fixed by moving the queue to a temporary 
place and creating a new queue. The old queue can be run later when the offending host 
returns to service. 

To do this, it is acceptable to move the entire queue directory: 



$ cd /usr/spool 

$ mv mqueue omqueue; mkdir mqueue; chmod 777 mqueue 

You should then kill the existing daemon (since it will still be processing in the old queue 
directory) and create a new daemon. 
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To run the old mail queue, run the following command: 



$ /usr/lib/sendmail -oQ/usr/spool/omqueue -q 

The -oQ flag specifies an alternate queue directory and the -q flag says to just run every 
job in the queue. Refer to Section 8.5 for details on configuration options. 

When the queue is finally emptied, you can remove the directory: 

$ rmdir /usr/spool/omqueue 

8.6.3 The Alias Database 

The alias database exists in two forms. One is a text form, maintained in the file 
/usr/lib/aliases. The aliases are of the form 

name: namel, name2, ... 

Only local names can be aliased. Aliases can be continued by starting any continuation 
lines with a space or a tab. Blank lines and lines beginning with a pound sign (#) are com- 
ments. 

The second form is processed by the dbm(3) library. This form is in the files 
/usr/lib/aliases. dir and /usr/lib/aliases. pag. This is the form that sendmail actually uses 
to resolve aliases. 



Rebuilding the Alias Database 

The database can be rebuilt explicitly by executing the command 
$ newaliases 

This is equivalent to giving sendmail the -bi flag: 

$ /usr/lib/sendmail -bi 

If the D option (see Section 8.5 for details on configuration options) is specified in the 
configuration, sendmail will rebuild the alias database automatically if possible when it is 
out of date. The conditions under which it will do this are either of the following: 

• The DBM version of the database is mode 666. 

• sendmail is running setuid to root. 

Auto-rebuild can be dangerous on heavily loaded machines with large alias files; if it might 
take more than five minutes to rebuild the database, there is a chance that several proc- 
esses will start the rebuild process simultaneously. 



Potential Problems 

There are a number of problems that can occur with the alias database. They all result 
from a sendmail process accessing the database while it is only partially built. This can 
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happen under two circumstances: one process accesses the database while another process 
is rebuilding it, or the process rebuilding the database halts (due to being killed or a sys- 
tem crash) before completing the rebuild. 

The sendmail facility has two techniques to try to relieve these problems. First, it ignores 
interrupts while rebuilding the database; this avoids the problem of someone aborting the 
process leaving a partially rebuilt database. Second, at the end of the rebuild it adds an 
alias of the form 

@: @ 

(which is not normally legal). Before sendmail will access the database, it checks to ensure 
that this entry exists. 

The a option is required in the configuration for this action to occur. This should normally 
be specified unless you are running delivermail in parallel with sendmail. It will wait up to 
five minutes for this entry to appear, at which point it will force a rebuild itself. Note that 
the D option must be specified in the configuration file for this operation to occur. 



List Owners 

If an error occurs on sending to a certain address, say “ X ”, sendmail will look for an alias 
of the form “owner-*” to receive the errors. This is typically useful for a mailing list where 
the submitter of the list has no control over the maintenance of the list itself; in this case 
the list maintainer would be the owner of the list. For example: 

unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser, 
sam@matisse 

owner-unix-wizards : eric@ucbarpa 

would cause “eric@ucbarpa” to get the error that will occur when someone sends to “unix- 
wizards” due to the inclusion of “nosuchuser” on the list. 

8.6.4 Per-User Forwarding (.forward Files) 

As an alternative to the alias database, any user can put a file with the name .forward in 
his or her home directory. If this file exists, sendmail redirects mail for that user to the 
list of addresses listed in the .forward file. For example, if the home directory for user 
“mckusick” has a .forward file with contents: 

mckusick@ernie 

kirk@calder 

then any mail arriving for “mckusick” will be redirected to the specified accounts. 

8.6.5 Special Header Lines 

Several header lines have special interpretations defined by the configuration file. Others 
have interpretations built into sendmail that cannot be changed without changing the code. 
These built-in interpretations are described here. 



Return-Receipt-To: 

If this header is sent, a message will be sent to any specified addresses when the final de- 
livery is complete, if the mailer has the 1 flag (local delivery) set in the mailer descriptor. 
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Errors-To: 

If errors occur anywhere during processing, this header will cause error messages to go to 
the listed addresses rather than to the sender. This is intended for mailing lists. 



Apparently-To: 

If a message comes in with no recipients listed in the message (in a To:, Cc:, or Bcc: line) 
then sendmail will add an “ Apparently-To :” header line for any recipients it is aware of. 
This is not put in as a standard recipient line to warn any recipients that the list is not 
complete. 

At least one recipient line is required under RFC 822. 



There are a number of configuration parameters you can want to change, depending on 
the requirements of your site. Most of these are set using an option in the configuration 
file. For example, the line “OT3d” sets option T to the value “3d” (three days). 



8.7.1 Timeouts 

All time intervals are set using a scaled syntax. For example, “10m” represents 10 min- 
utes, whereas “2h30m” represents two and a half hours. The full set of scales is 



s seconds 

m minutes 

h hours 

d days 

w weeks 

Queue Interval 

The argument to the -q flag specifies how often a subdaemon will run the queue. This is 
typically set to between five minutes and one half hour. 



Read Timeouts 

It is possible to time out when reading the standard input or when reading from a remote 
SMTP server. Technically, this is not acceptable within the published protocols. However, 
it might be appropriate to set it to something large in certain environments (such as an 
hour). This will reduce the chance of large numbers of idle daemons piling up on your 
system. This timeout is set by using the r option in the configuration file. 



Message Timeouts 

After being in the queue for a few days, a message will time out. This is to ensure that at 
least the sender is aware of the inability to send a message. The timeout is typically set to 
three days. This timeout is set by using the T option in the configuration file. 
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The time of submission is set in the queue, rather than the amount of time left until 
timeout. As a result, you can flush messages that have been hanging for a short period by 
running the queue with a short message timeout. For example, 

$ /usr/lib/sendmail -oTld -q 

will run the queue and flush anything that is one day old. 

8.7.2 Delivery Mode 

There are a number of delivery modes that sendmail can operate in, set by the d configu- 
ration option. These modes specify how quickly mail will be delivered. Legal modes are 

i Deliver interactively (synchronously) 

b Deliver in background (asynchronously) 

q Queue only (don't deliver) 

There are tradeoffs. Mode i passes the maximum amount of information to the sender, but 
is hardly ever necessary. Mode q puts the minimum load on your machine, but means that 
delivery can be delayed for up to the queue interval. Mode b is probably a good compro- 
mise. However, this mode can cause large numbers of processes if you have a mailer that 
takes a long time to deliver a message. 

8.7.3 Log Level 

The level of logging can be set for sendmail. The default using a standard configuration 
table is level 9. The levels are as follows: 

0 No logging. 

1 Major problems only. 

2 Message collections and failed deliveries. 

3 Successful deliveries. 

4 Messages being deferred (due to a host being down, etc.). 

5 Normal message queueups. 

6 Unusual but benign incidents, for example, trying to process a locked 
queue file. 

9 Log internal queue ID to external message ID mappings. This can be use- 

ful for tracing a message as it travels between several hosts. 

12 Several messages that are basically only of interest when debugging. 

16 Verbose information regarding the queue. 

8.7.4 File Modes 

There are a number of files that can have a number of modes. The modes depend on 
what functionality you want and the level of security you require. 
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When to Use suid 

The sendmail facility can safely be made setuid to root. At the point where it is about to 
exec(2) a mailer, it checks to see if the user ID is 0; if so, it resets the user ID and group 
ID to a default (set by the u and g options) . (This can be overridden by setting the S flag 
to the mailer for mailers that are trusted and must be called as root.) However, this will 
cause mail processing to be accounted (using sa(8)) to root rather than to the user sending 
the mail. 



Temporary File Modes 

The mode of all temporary files that sendmail creates is determined by the F option. Rea- 
sonable values for this option are 0600 and 0644. If the more permissive mode is selected, 
it will not be necessary to run sendmail as root at all (even when running the queue) . 



Should an Alias Database Be Writable? 

The database that sendmail actually used is represented by the two files aliases, dir and 
aliases, pag (both in /usr/lib). The mode on these files should match the mode on 
/usr/lib/aliases. If aliases is writable and the DBM files (aliases. dir and aliases. pag) are 
not, users will be unable to reflect their desired changes through to the actual database. 
However, if aliases is read-only and the DBM files are writable, a slightly sophisticated 
user can arrange to steal mail anyway. 

If your DBM files are not writable by the world or you do not have auto-rebuild enabled 
(with the D option), then you must be careful to reconstruct the alias database each time 
you change the text version: 



$ newaliases 

If this step is ignored or forgotten, any intended changes will also be ignored or forgotten. 



8.8 The Configuration File 

This section describes the configuration file in detail, including hints on how to write one 
of your own if you have to. An overview of the configuration file is given first, followed 
by details of the semantics. 

8,8.1 Syntax 

The configuration file is organized as a series of lines, each of which begins with a single 
character defining the semantics for the rest of the line. Lines beginning with a space or a 
tab are continuation lines (although the semantics are not well defined in many places). 
Blank lines and lines beginning with a pound sign (#) are comments. 
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R and S — Rewriting Rules 

The core of address parsing are the rewriting rules. These are an ordered production sys- 
tem. sendmail scans through the set of rewriting rules looking for a match on the left 
hand side (LHS) of the rule. When a rule matches, the address is replaced by the right 
hand side (RHS) of the rule. 

There are several sets of rewriting rules. Some of the rewriting sets are used internally and 
must have specific semantics. Other rewriting sets do not have specifically assigned seman- 
tics, and can be referenced by the mailer definitions or by other rewriting sets. 

The syntax of these two commands are 

S n 

Sets the current rule set being collected to n. If you begin a rule set more than once, it 
deletes the old definition. 

R lhs rhs comments 

The fields must be separated by at least one tab character; there can be embedded spaces 
in the fields. The lhs is a pattern that is applied to the input. If it matches, the input is 
rewritten to the rhs. The comments are ignored. 



D — Define Macro 

Macros are named with a single character. These can be selected from the entire ASCII 
set, but user-defined macros should be selected from the set of uppercase letters only. 
Lowercase letters and special symbols are used internally. 

The syntax for macro definitions is 

D xval 

where x is the name of the macro and val is the value it should have. Macros can be in- 
terpolated in most places by using the escape sequence $jc. 



C and F — Define Classes 

Classes of words can be defined to match on the left-hand side of rewriting rules. For ex- 
ample a class of all local names for this site might be created so that attempts to send to 
oneself can be eliminated. These can either be defined directly in the configuration file or 
read in from another file. Classes can be given names from the set of uppercase letters. 
Lowercase letters and special characters are reserved for system use. 

The syntax is 

C cwordl word2 ... 

F cfile [ format ] 
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The first form defines the class C to match any of the named words. It is permissible to 
split them among multiple lines; for example, the two forms: 

CHmonet ucbmonet 
and 

CHmonet 

CHucbmonet 

are equivalent. The second form reads the elements of the class C from the named file; 
the format is a scanf(3) pattern that should produce a single string. 



M — Define Mailer 

Programs and interfaces to mailers are defined in this line. The format is 
M name, { fields value}* 

where name is the name of the mailer (used internally only) and the “field=name” pairs 
define attributes of the mailer. Fields are 



P[ath] 


The pathname of the mailer. 


F[lags] 


Special flags for this mailer. 


S[ender] 


A rewriting set for sender addresses. 


Recipient] 


A rewriting set for recipient addresses. 


A[rgv] 


An argument vector to pass to this mailer. 


E[oI] 


The end-of-line string for this mailer. 


M[axsize] 


The maximum message length to this mailer. 



Only the first character of the field name is checked. 



H — Define Header 

The format of the header lines that sendmail inserts into the message are defined by the 
H line. The syntax of this line is 

H[? mf lags'!] hnameihtemplate 

Continuation lines are reflected directly into the outgoing message. The htemplate is macro 
expanded before insertion into the message. If the mflags (surrounded by question marks) 
are specified, at least one of the specified flags must be stated in the mailer definition for 
this header to be automatically output. If one of these headers is in the input it is reflected 
to the output regardless of these flags. 

Some headers have special semantics that will be described below. 
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O — Set Option 



There are a number of “random” options that can be set from a configuration file. Options 
are represented by single characters. The syntax of this line is 

O ovalue 

This sets option o to be value. Depending on the option, value can be a string, an integer, 
a boolean (with legal values t, T, f, or F; the default is TRUE), or a time interval. 



T — Define Trusted Users 

Trusted users are those users who are permitted to override the sender address by using 
the -f flag. These typically are root, uucp, and network, but for some users it can be con- 
venient to extend this list to include other users, perhaps to support a separate login for 
each host. The syntax of this line is 

T userl user 2... 

There can be more than one of these lines. 



P — Precedence Definitions 

Values for the “Precedence:” field can be defined using the P control line. The syntax of 
this field is 



P name=num 

When the name is found in a “Precedence:” field, the message class is set to num . Higher 
numbers mean higher precedence. Numbers less than 0 have the special property that error 
messages will not be returned. The default precedence is 0. For example, our list of prece- 
dences is 

Pf irst-class=0 
Pspecial-delivery=100 
Pj unk=-100 



8.8.2 Semantics 

This section describes the semantics of the configuration file. 



Special Macros and Conditionals 

Macros are interpolated using the construct $x, where x is the name of the macro to be 
interpolated. In particular, lower case letters are reserved to have special semantics, used 
to pass information in or out of sendmail, and some special characters are reserved to 
provide conditionals, etc. 
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The following macros must be defined to transmit information into sendmail: 



e The SMTP entry message 

j The “official” domain name for this site 

1 The format of the UNIX system from line 

n The name of the daemon (for error messages) 

o The set of "operators” in addresses 

q The default format of sender address 

The $e macro is printed out when SMTP starts up. The first word must be the $j macro. 
The $j macro should be in RFC821 format. The $1 and $n macros can be considered con- 
stants except under terribly unusual circumstances. The $o macro consists of a list of char- 
acters which will be considered tokens and which will separate tokens when doing parsing. 
For example, if r were in the $o macro, then the input address would be scanned as three 
tokens: add, r, and ess. Finally, the $q macro specifies how an address should appear in a 
message when it is defaulted. For example, 

De$j sendmail $v ready at $b 

DnMAI LER-DAEMON 

DlFrom $g $d 

Do. :%@! W 

Dq$g$?x ($x)$. 

Dj$H.$D 

An acceptable alternative for the $q macro is $?x$x $.<$g>. These correspond to the fol- 
lowing two formats: 

eric@Berkeley (Eric Allman) 

Eric Allman <eric@Berkeley> 

Some macros are defined by sendmail for interpolation into argv’s for mailers or for other 
contexts. These macros are 



a The origination date in ARPANET format, 

b The current date in ARPANET format, 

c The hop count. 

d The date in the UNIX system (ctime) format, 

f The sender (from) address, 

g The sender address relative to the recipient, 

h The recipient host. 
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The queue ID. 



p sendmail’s pid . 

r Protocol used, 

s Sender’s host name. 

t A numeric representation of the current time, 

u The recipient user, 

v The version number of sendmail. 

w The host name of this site, 

x The full name of the sender, 

y The IDof the sender’s tty. 

z The home directory of the recipient. 

There are three types of dates that can be used. The $a and $b macros are in ARPANET 
format; $a is the time as extracted from the “Date:” line of the message (if there was 
one), and $b is the current date and time (used for postmarks). If no “Date:” line is 
found in the incoming message, $a is set to the current time also. The $d macro is equiva- 
lent to the $a macro in the UNIX system ( ctime ) format. 

The $f macro is the ID of the sender as originally determined; when mailing to a specific 
host the $g macro is set to the address of the sender relative to the recipient. For exam- 
ple, if “bollard@matisse” is sent from the machine “ucbarpa” the $f macro will be “eric” 
and the $g macro will be “eric@ucbarpa.” 

The $x macro is set to the full name of the sender. This can be determined in several 
ways. It can be passed as flag to sendmail. The second choice is the value of the “Full- 
name:” line in the header if it exists, and the third choice is the comment field of a 
“From:” line. If all of these fail, and if the message is being originated locally, the full 
name is looked up in the /etc/pass wd file. 

When sending, the $h, $u, and $z macros get set to the host, user, and home directory (if 
local) of the recipient. The first two are set from the $@ and $: part of the rewriting rules, 
respectively. 

The $p and $t macros are used to create unique strings (for example, for the “Message- 
id:” field). The $i macro is set to the queue ID on this host; if put into the time stamp 
line it can be extremely useful for tracking messages. The $y macro is set to the ID of the 
terminal of the sender (if known) ; some systems like to put this in the UNIX system 
“From” line. The $v macro is set to be the version number of sendmail; this is normally 
put in time stamps and has been proven extremely useful for debugging. The $w macro is 
set to the name of this host if it can be determined. The $c field is set to the “hop 
count,” that is, the number of times this message has been processed. This can be deter- 
mined by the -h flag on the command line or by counting the time stamps in the message. 
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The $r and $s fields are set to the protocol used to communicate with sendmail and the 
sending host name; these are not supported in the current version. 

Conditionals can be specified by using the syntax: 

$?x textl $| text2 $. 

This interpolates textl if the macro $x is set, and textl otherwise. The “else” ( $|) clause 
can be omitted. 



Special Classes 

The class $=w is set to be the set of all names this host is known by. This can be used to 
delete local host names. 



The Left-Hand Side 

The left-hand side (LHS) of rewriting rules contains a pattern. Normal words are simply 
matched directly. Metasyntax is introduced by using a dollar sign. The metasymbols are 

$* Match 0 or more tokens. 

$+ Match one or more tokens. 

$- Match exactly one token. 

$=x Match any token in class x. 

$~jc Match any token not in class x. 

If any of these match, they are assigned to the symbol $n for replacement on the right- 
hand side (RHS), where n is the index in the LHS. For example, if the LHS: 

$-:$+ 

is applied to the input: 

UCBARPA:eric 

the rule will match, and the values passed to the RHS will be: 

$1 UCBARPA 
$2 eric 

The Right-Hand Side 

When the right-hand side of a rewriting rule matches, the input is deleted and replaced by 
the right-hand side. Tokens are copied directly from the RHS unless they are begin with a 
dollar sign. Metasymbols are as follows: 
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$n 


Substitute indefinite 


$>n 


“Call” rule set n. 


%#mailer 


Resolve to mailer . 


%@host 


Specify host. 


$:user 


Specify user. 



The $n syntax substitutes the corresponding value from a $+, $-, $*, $=, or $- match on 
the LHS. It can be used anywhere. 

The $> n syntax causes the remainder of the line to be substituted as usual and then 
passed as the argument to rule set n. The final value of rule set n then becomes the substi- 
tution for this rule. 

The $# syntax should only be used in rule set 0. It causes evaluation of the rule set to ter- 
minate immediately, and signals to sendmail that the address has completely resolved. The 
complete syntax is 

$#mailer$@host $ : user 

This specifies the {mailer, host, user} 3-tuple necessary to direct the mailer. If the mailer 
is local, the host part can be omitted. The mailer and host must be a single word, but the 
user can be multipart. 

An RHS can also be preceeded by a $@ or a $: to control evaluation. A $@ prefix causes 
the rule set to return with the remainder of the RHS as the value. A $: prefix causes the 
rule to terminate immediately, but the rule set to continue; this can be used to avoid con- 
tinued application of a rule. The prefix is stripped before continuing. 

The $@ and $: prefixes can precede a $> spec; for example: 

R$+ $:$>7$1 

matches anything, passes that to rule set seven, and continues; the $: is necessary to avoid 
an infinite loop. 

Rule Sets Applied to Recipient Addresses 

As shown in Figure 8-1, there are five rewriting sets that have specific semantics. 
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Figure 8-1. Rewriting Set Semantics for Recipient Addresses 



The following rule sets are applied to recipient addresses: 



® Rule set 3 turns an address into “canonical form,” that is, a form that is ready for 
internal use. This form should have the basic syntax: 

local-part@host-domain-spec 

If no “@” sign is specified, then the host-domain-spec can be appended from the 
sender address (if the C flag is set in the mailer definition corresponding to the 
sending mailer) . Rule set 3 is applied by sendmail before doing anything with any 
address. 

© Rule set 0 is applied after rule set 3 to addresses that are going to actually specify 
recipients. It must resolve to a { mailer , host , user} triple. The mailer must be de- 
fined in the mailer definitions from the configuration file. The host is defined into 
the $h macro for use in the argv expansion of the specified mailer. 

© Rule set 2 is globally applied to all recipient addresses in the mail header fields: 

To :, Cc:, Apparently-to: , and Bcc:. They are applied before any specification in 
the mailer definition. They must never resolve. 

® Rule set 4 is applied to all addresses in the message. It is typically used to trans- 
late internal to external form by removing any “internal-only” additions prior to 
sending mail to the “outside” world. 



Rule Sets Applied to Sender Addresses 

As shown in Figure 8-2, there are five rewriting sets that have specific semantics. 
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Figure 8-2. Rewriting Set Semantics for Sender Addresses 



The following rule sets are applied to sender addresses: 

• Rule set 3 turns an address into “canonical form,” that is, a form that is ready for 
internal use. This form should have the basic syntax: 

local-part@host-domain-spec 

If no “@” sign is specified, then the host-domain-spec can be appended from the 
sender address (if the C flag is set in the mailer definition corresponding to the 
sending mailer), rule set three is applied by sendmail before doing anything with 
any address. 

© Rule set 1 is globally applied to the sender address in either of the mail header 
field: From: or Apparently-from: . It is applied before any specification in the 
mailer definition and must never resolve. 

© Rule set 4 is applied to all addresses in the message. It is typically used to trans- 
late internal to external form by removing any “internal-only” additions prior to 
sending mail to the “outside” world. 

Mailer Flags 

There are a number of flags that can be associated with each mailer, each identified by a 
letter of the alphabet. Many of them are assigned semantics internally. Refer to Section 8.6 
for details. 
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The “error* ’ Mailer 



The mailer with the special name “error” can be used to generate a user error. The (op- 
tional) host field is a numeric exit status to be returned, and the user field is a message to 
be printed. For example, the entry: 

$#error$ -.Host unknown in this domain 

on the RHS of a rule will cause the specified error to be generated if the LHS matches. 
This mailer is only functional in rule set 0. 

8.8-3 Building a Configuration File from Scratch 

Building a configuration table from scratch is an extremely difficult job. Fortunately, it is 
almost never necessary to do so; nearly every situation that can come up can be resolved 
by changing an existing table. In any case, it is critical that you understand what it is that 
you are trying to do and come up with a philosophy for the configuration table. This sec- 
tion is intended to explain what the real purpose of a configuration table is and to give you 
some ideas for what your philosophy might be. 



What You Are Trying to Do 

The configuration table has three major purposes. The first and simplest is to set up the 
environment for sendmail. The secondis to rewrite addresses in the message. This should 
be done in two phases. The first phase maps addresses in any format into a canonical 
form. This should be done in rule set 3. The second phase maps this canonical form into 
the syntax appropriate for the receiving mailer. 

The third purpose is to map addresses into the actual set of instructions necessary to get 
the message delivered. 

Philosophy 

The particular philosophy you choose will depend heavily on the size and structure of your 
organization. 

One general point applies to all philosophies: it is almost always a mistake to try to do full 
name resolution. For example, if you are trying to get names of the form user@host to the 
ARPANET, it does not pay to route them to xyzvax!decvax!ucbvax!c70:M.S£r@/iayt since 
you then depend on several links not under your control. The best approach to this prob- 
lem is to simply forward to xyzvax! user@host and let xyzvax worry about it from there. In 
summary, just get the message closer to the destination, rather than determining the full 
path. 



Large Site, Many Hosts — Minimum Information 

You can have decided that the only reasonable philosophy in our environment is to desig- 
nate one host as the guru for your site. It must be able to resolve any piece of mail it re- 
ceives. The other sites should have the minimum amount of information they require. In 
addition, any information they do have should be hints rather than solid information. 

For example, a typical site on a local ETHERNET is “monet.” The site monet has a list of 
known ETHERNET hosts; if it receives mail for any of them, it can do direct delivery. If it 
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receives mail for any unknown host, it just passes it directly to “ucbvax,” the master host. 
The master host ucbvax can determine that the host name is illegal and reject the mes- 
sage, or can be able to do delivery. However, it is important to note that when a new 
ETHERNET host is added, the only host that must have its tables updated is ucbvax; the 
others can be updated as convenient, but this is not critical. 

This picture is slightly muddied due to network connections that are not actually located on 
ucbvax. For example, the TCP connection is currently on “ucbarpa.” However, monet 
does not know about this; the information is hidden totally between ucbvax and ucbarpa. 
Mail going from monet to a TCP host is transferred via the ETHERNET from monet to 
ucbvax, then via the ETHERNET from ucbvax to ucbarpa, and then is submitted to the 
ARPANET. This can be an acceptable tradeoff. 

An interesting point is that it would be possible to update monet to send TCP mail directly 
to ucbarpa if the load got too high; if monet failed to note a host as a TCP host it would 
go via ucbvax as before, and if monet incorrectly sent a message to ucbarpa it would still 
be sent by ucbarpa to ucbvax as before. The only problem that can occur is loops, as if 
ucbarpa thought that ucbvax had the TCP connection and vice versa. For this reason, 
updates should always happen to the master host first. 

This philosophy results as much from the need to have a single source for the configuration 
files (typically built using m4(l) or some similar tool) as any logical need. Maintaining 
more than three separate tables by hand is essentially an impossible job. 



Small Site — Complete Information 

A small site (two or three hosts) can find it more reasonable to have complete information 
at each host. This would require that each host know exactly where each network connec- 
tion is, possibly including the names of each host on that network. As long as the site re- 
mains small and the the configuration remains relatively static, the update problem will 
probably not be too great. 



Single Host 

This is in some sense the trivial case. The only major issue is trying to ensure that you 
don’t have to know too much about your environment. For example, if you have a uucp 
connection you might find it useful to know about the names of hosts connected directly to 
you, but this is really not necessary since this can be determined from the syntax. 



Relevant Issues 

The following characters have special interpretations: 

< > ( ) ” \ 

Essentially, each host is given a name which is a right-to-left dot qualified pseudopath 
from a distinguished root. The elements of the path need not be physical hosts; the do- 
main is logical rather than physical. For example, at Berkeley one legal host is 
“a.cc.berkeley.arpa”; reading from right to left, “arpa” is a top-level domain (related to, 
but not limited to, the physical ARPANET), “berkeley” is both an ARPANET host and a 
logical domain which is actually interpreted by a host called ucbvax (which is actually just 
the “major” host for this domain), “cc” represents the Computer Center, (in this case a 
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strictly logical entity), and “a” is a host in the Computer Center; this particular host hap- 
pens to be connected via berknet, but other hosts might be connected via one of two 
ETHERNETS or some other network. 



How to Proceed 

Once you have decided on a philosophy, it is worth examining the available configuration 
tables to decide if any of them are close enough to steal major parts. Even under the worst 
of conditions, there is a fair amount of boiler plate that can be collected safely. 

The next step is to build rule set 3. This will be the hardest part of the job. Beware of do- 
ing too much to the address in this rule set, since anything you do will reflect through to 
the message. In particular, stripping of local domains is best deferred, since this can leave 
you with addresses with no domain spec at all. Since sendmail likes to append the sending 
domain to addresses with no domain, this can change the semantics of addresses. Also try 
to avoid fully qualifying domains in this rule set. Although technically legal, this can lead to 
unpleasantly and unnecessarily long addresses reflected into messages. 

Once you have rule set 3 finished, the other rule sets should be relatively trivial. If you 
need hints, examine the supplied configuration tables. 



Testing The Rewriting Rules: The -bt Flag 

When you build a configuration table, you can do a certain amount of testing using the 
“test mode” of sendmail. For example, you could invoke sendmail as 

$ sendmail -bt -Ctest.cf 

which would read the configuration file test.cf and enter test mode. In this mode, you en- 
ter lines of the form: 

rwset address 

where rwset is the rewriting set you want to use and address is an address to apply the set 
to. Test mode shows you the steps it takes as it proceeds, finally showing you the address 
it ends up with. You can use a comma separated list of rwsets for sequential application of 
rules to an input; rule set 3 is always applied first. For example: 

1,21,4 monet: bollard 

first applies rule set 3 to the input monet: bollard, rule set 1 is then applied to the output 
of rule set 3, followed similarly by rule sets 21 and 4. 

If you need more detail, you can also use the -d21 flag to turn on more debugging. For 
example, 

$ sendmail -bt -d21.99 

turns on an incredible amount of information; a single word address is probably going to 
print out several pages worth of information. 



Building Mailer Descriptions 

To add an outgoing mailer to your mail system, you will have to define the characteristics 
of the mailer. 



Sendmail Configuration and Usage 



8-27 




Each mailer must have an internal name. This can be arbitrary, except that the names lo- 
cal and prog must be defined. 

The pathname of the mailer must be given in the P field. If this mailer should be accessed 
via an IPC connection, use the string [IPC] instead. 

The F field defines the mailer flags. You should specify an f or r flag to pass the name of 
the sender as a -f or -r flag respectively. These flags are only passed if they were passed to 
sendmail, so that mailers that give errors under some circumstances can be placated. If 
the mailer is not picky you can just specify -f $g in the argv template. If the mailer must 
be called as root the S flag should be given; this will not reset the user ID before calling 
the mailer, sendmail must be running setuid to root for this to work. 

If this mailer is local (that is, will perform final delivery rather than another network hop) 
the 1 flag should be given. Quote characters (backslashes and ” characters) can be stripped 
from addresses if the s flag is specified; if this is not given they are passed through. If the 
mailer is capable of sending to more than one user on the same host in a single transaction 
the m flag should be stated. If this flag is on, then the argv template containing $u will be 
repeated for each unique user on a given host. The e flag will mark the mailer as being 
“expensive,” which will cause sendmail to defer connection until a queue run. The c con- 
figuration option must be given for this to be effective. 

An unusual case is the C flag. This flag applies to the mailer that the message is received 
from, rather than the mailer being sent to; if set, the domain spec of the sender (that is, 
the “@host. domain” part) is saved and is appended to any addresses in the message that 
do not already contain a domain spec. For example, a message of the form: 

From: eric@ucbarpa 
To: wnj@monet, mckusick 

will be modified to: 

From : er ic@ucbarpa 

To: wnj@monet, mckusick@ucbarpa 

if and only if the C flag is defined in the mailer corresponding to eric@ucbarpa. 

The S and R fields in the mailer description are per-mailer rewriting sets to be applied to 
sender and recipient addresses respectively. These are applied after the sending domain is 
appended and the general rewriting sets (numbers one and two) are applied, but before the 
output rewrite (rule set 4) is applied. A typical use is to append the current domain to ad- 
dresses that do not already have a domain. For example, a header of the form: 

From: eric 

might be changed to be: 

From : er i c@ucbarpa 
or 

From: ucbvaxleric 
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depending on the domain it is being shipped into. These sets can also be used to do spe- 
cial-purpose output rewriting in cooperation with rule set 4. 

The E field defines the string to use as an end-of-line indication. A string containing only 
newline is the default. The usual backslash escapes (\r, \n, \f, \b) can be used. 

Finally, an argv template is given as the E field. It can have embedded spaces. If there is 
no argv with a $u macro in it, sendmail will speak SMTP to the mailer. If the pathname 
for this mailer is [IPC] , the argv should be 

IPC $h [ port ] 

where port is the optional port number to connect to. 

For example, the specifications: 

Mlocal, P=/bin/mail, F=rlsm S=10, R=20, A=mail -d $u 
Mether, P=[IPC] , F=meC, S=ll, R=21, A=IPC $h, M=100000 

specifies a mailer to do local delivery and a mailer for ETHERNET delivery. The first is 
called local, is located in the file /bin/mail, takes a picky -r flag, does local delivery, 
quotes should be stripped from addresses, and multiple users can be delivered at once; rule 
set 10 should be applied to sender addresses in the message and rule set 20 should be ap- 
plied to recipient addresses; the argv to send to a message will be the word mail, the word 
-d, and words containing the name of the receiving user. If a -r flag is inserted it will be 
be connected to via an IPC connection, it can handle multiple users at once, connections 
should be deferred, and any domain from the sender address should be appended to any 
receiver name without a domain; sender addresses should be processed by rule set 11 and 
recipient addresses by rule set 21. There is a 100,000 byte limit on messages passed 
through this mailer. 



8.9 Summary of Support Files 

This is a summary of the support files that sendmail creates or generates. 



/usr/lib/sendmail 

/usr/bin/newaliases 

/usr/bin/mailq 

/usr/lib/sendmail. cf 
/usr/lib/sendmail. fc 
/usr/lib/sendmail. hf 
/ usr/lib/sendmail. st 



The binary of sendmail. 

A link to /usr/lib/sendmail; causes the alias database to 
be rebuilt. Running this program is completely equivalent 
to giving sendmail the -bi flag. 

Prints a listing of the mail queue. This program is equiva- 
lent to using the -bp flag to sendmail. 

The configuration file, in textual form. 

The configuration file represented as a memory image. 

The SMTP help file. 

A statistics file; need not be present. 
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/usr/lib/aliases 
/usr/lib/aliases. {pag,dir} 
/etc/syslog 
/etc/syslog.conf 
/etc/syslog. pid 
/usr/spool/mqueue 

/usr/spool/ mqueue/qf * 
/usr/spool/ mqueue/df * 
/usr/spool/ mqueue/lf * 
/usr/spool/mqueue/tf* 

/usr/spool/mqueue/nf* 

/usr/spool/mqueue/xf* 



The textual version of the alias file. 

The alias file in dbm(3) format. 

The program to do logging. 

The configuration file for syslog. 

Contains the process id of the currently running syslog. 

The directory in which the mail queue and temporary files 
reside. 

Control (queue) files for messages. 

Data files. 

\ 

Lock files. 

Temporary versions of the qf files, used during queue file 
rebuild. 

A file used when creating a unique ID. 

A transcript of the current session. 

88 
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NAME 

intro - introduction to maintenance commands and application programs 
DESCRIPTION 

This section describes, in alphabetical order, commands that are used chiefly for system 
maintenance and administration purposes. The commands in this section should be 
used along with those listed in the Using Your SysV Environment and the SysV 
Programmer’ s Reference. References of the form name(l), (2), (3), (4) and (5) refer to 
entries in the above manuals. References of the form name(lM), name(7) or name(8) 
refer to entries in this manual. 



COMMAND SYNTAX 

Unless otherwise noted, commands described in this section accept options and other 
arguments according to the following syntax: 

name [ option(s )] [cmdarg(s)\ 
where: 



name 

option 



noargletter 

argletter 

optarg 

cmdarg 



Is the name of an executable file 

- noargletter (s) or, 

- argletter ooptarg 

where <> is optional white space 

Is a single letter representing an option without an argument 

Is a single letter representing an option requiring an argument 

Is an argument (character string) satisfying preceding argletter 

Pathname (or other command argument) not beginning with - or, - by 
itself indicating the standard input 



CAUTION 

Not all commands follow the above syntax. 



DIAGNOSTICS 

On termination, each command returns two bytes of status, one supplied by the system 
and giving the cause for tennination, and (in the case of “normal” termination) one 
supplied by the program (see \vai((2) and exit(2)). The fonner byte is 0 for normal ter- 
mination; the latter is customarily 0 for successful execution and nonzero to indicate 
troubles such as erroneous parameters, bad or inaccessible data. It can be called “exit 
code”, “exit status”, or “return code”, and is described only where special conven- 
tions are involved. 



SEE ALSO 

getopt(l) getopt(3C) 
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UUTRY(IM) SysV UUTRY(IM) 



NAME 

Uutry — try to contact remote system with debugging on 
SYNOPSIS 

/usr/lib/uucp/Uutry [ -x debugjevel ] [ — r ] systemjiame 

DESCRIPTION 

Uutry is a shell that is used to invoke uucico to call a remote site. Debugging is turned 
on (default is level 5); 

OPTIONS 

—xdebugjevel Overrides the default debugging level (level 5.) The level is set to 
debugjevel . 

-r Overrides the retry time in /usr/spool/uucp/.status. The debugging 

output is put in file /t mp/ systemjiame . A tail -f of the output is exe- 
cuted. DELETE or BREAK gives control back to the terminal while 
uucico continues to run, putting its output in /tmp/ system name . 

FILES 

/usr/lib/uucp/Svstems 

/usr/lib/uucp/Permissions 

/usr/lib/uucp/Devices 

/usr/lib/uucp/Maxuuxqts 

/usr/lib/uiicp/Maxuuschecls 

/usr/spool/uucp/* 

/usr/spool/locks/LCK* 

/usr/spool/uucppublic/* 

/tnip/systemna me 

SEE ALSO 

uucico(lM). 
uucp(lC), uux(lC) 
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NAME 

accept, reject - allow or prevent Ip requests 
SYNOPSIS 

/ us r/l i b/accep t destinations 
/usr/lib/reject [— r [ reason ]] destinations 

DESCRIPTION 

accept allows lp(l) to accept requests for named destinations. A destination can be 
either a line printer (LP) or a class of printers. Use Ipstat(l) to find the status of desti- 
nations . 

reject prevents lp(l) from accepting requests for named destinations . A destination 
can be either a line printer (LP) or a class of printers. Use Ipstat(l) to find the status of 
destinations . 

OPTIONS 

The following option is used only with reject. 

-r [reason] Associates a reason with preventing Ip from accepting requests. 

This reason applies to all printers mentioned up to the next — r 
option. Ip and Ipstat(l) report a reason when you direct requests 
to named destinations. If the -r option is not present or the -r 
option is given without a reason , then the default reason is used. 

FILES 

/usr/spool/lp/* Spooling directories 

SEE ALSO 

lpadmin (1M), lpsched (1M), enable (l), Ip (I), lpstat (1) 
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NAME 

arp - address resolution display and control 

SYNOPSIS 

arp hostname 
arp -a 

arp -d hostname 

arp -s hostname ether_addr [ temp ] [ pub ] [ trail ] 
arp -f filename 

DESCRIPTION 

The arp program displays and modifies the Intemet-to-ETHERNET address translation 
tables used by the address resolution protocol (arp). 

With no flags, the program displays the current ARP entry for hostname. You may 
specify the host by name or by number, using Internet dot notation. 

OPTIONS 

-a Display all of the current ARP entries in the internal file. 

-d hostname A super-user may delete an entry for the host called hostname. 

-s hostname ether addr [ temp ] [ pub ] [ trail ] 

Create an ARP entry for the host called hostname with the ETHERNET 
address ether addr. The ETHERNET address is given as six hex bytes 
separated by colons. The entry will be pennanent unless you specify the 
word temp in the command. If you specify the word pub, the entry will 
be “published”; that is, this system will act as an ARP server, respond- 
ing to requests for hostname even though the host address is not its own. 
The word trail indicates that trailer encapsulations may be sent to this 
host. 

-f filename Read the file filename and set multiple entries in the ARP tables. Entries 

in the file should be of the form 

hostname ether addr [ temp ] [ pub ] [ trail ) 

with argument meanings as given above. 

SEE ALSO 

inet( ), arp( ), ifconfig(lM); 

Configuring and Managing TCP I IP. 
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NAME 

captoinfo - convert a termcap description into a terminfo description 
SYNOPSIS 

captoinfo [-v ...] [-V] [-1] [— \v width] file ... 

DESCRIPTION 

captoinfo looks in file for termcap descriptions. For each one found, an equivalent 
terminfo(4) description is written to standard output, along with any comments found. 
A description that is expressed as relative to another description (as specified in the 
termcap tc= field) reduces to the minimum superset before being output. 

If no file is given, then use the environment variable TERMCAP for the filename or 
entry. If TERMCAP is a full pathname to a file, only the temninal whose name is 
specified in the environment variable TERM is extracted from that file. If the environ- 
ment variable TERMCAP is not set, then read the file /etc/termcap. 

OPTIONS 

— v Prints tracing information on standard error as the program runs. Speci- 

fying additional — v options causes more detailed information to be 
printed. 

-V Prints the version of the program in use on standard error and exit. 

— 1 Causes the fields to print one to a line. Otherwise, the fields are printed 

several to a line, up to a maximum width of 60 characters. 

— w width Changes the output to width characters. 

NOTES 

captoinfo should be used to convert termcap entries to terminfo(4) entries since the 
termcap database may not be supplied in future releases. 

The short two-letter name at the beginning of the list of names in a termcap entry has 
been removed. 

CAVEATS 

Certain termcap defaults are assumed to be true. For example, the bell character ( ter- 
minfo bel) is assumed to be CTRL/G. The linefeed capability (termcap nl) is assumed 
to be the same for both cursor jlown and scroll forward {terminfo cud l and ind, 
respectively.) Padding infonnation is assumed to belong at the end of the string. 

The algorithm used to expand parameterized information for termcap fields such as 
cursor jposition (termcap cm, terminfo cup ) sometimes produces a string which, 
though technically correct, may not be optimal. In particular, the rarely used termcap 
operation %n produces strings that are especially long. Most occurrences of these 
non-optimal strings are flagged with a warning message and may need to be recoded by 
hand. 
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FILES 

/usr/lib/terminfo/?/* Compiled terminal description database 
DIAGNOSTICS 

tgetent failed with return code n (reason) . 

The termcap entry is not valid. In particular, check for an 
invalid ’tc=’ entry. 

unknown type given for the termcap code cc. 

The termcap description had an entry for cc whose type was not 
Boolean, numeric or string. 

wrong type given for the boolean (numeric, string) 
termcap code cc . 

The Boolean termcap entry cc was entered as a numeric or string 
capability. 

the boolean (numeric, string) termcap code cc is not 
a valid name. 

An unknown termcap code was specified. 

tgetent failed on TERM=term. 

The tenninal type specified could not be found in the termcap 
file. 

TERM=term: cap cc (info ii) is NULL: removed 

The termcap code was specified as a null string. The correct 
way to cancel an entry is with an as in ’:bs@:\ Giving a 
null string could cause incorrect assumptions to be made by the 
software which uses termcap or terminfo. 

a function key for cc was specified, but it already 
has the value w. 

When parsing the ko capability, the key cc was specified as hav- 
ing the same value as the capability cc, but the key cc already 
had a value assigned to it. 

the unknown termcap name cc was specified in the 
ko termcap capability. 

A key was specified in the ko capability which could not be han- 
dled. 

the vi character v (info iil) has the value xx, 
but ma gives n. 

The ma capability specified a function key with a value different 
from that specified in another setting of the same key. 
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the unknown vi key v was specified in the ma 
termcap capability. 

A vi(l) key unknown to captoinfo was specified in the ma capa- 
bility. 

Warning: termcap sg (nn) and termcap ug (nn) had 
different values. 

terminfo assumes that the sg (now xmc) and ug values were the 
same. 

Warning: the string produced for ii may be inefficient. 

The parameterized string being created should be rewritten by 
hand. 

Null termname given. 

The terminal type was null. This is given if the environment 
variable TERM is not set or is null. 



cannot open file for reading. 

The specified file could not be opened. 



SEE ALSO 

infocmp(lM), tic(lM). 
curses (3X), tenninfo(4) 
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NAME 

cpboot - copy the system boot file sysboot 
SYNOPSIS 

/etc/cpboot source directory target directory 

DESCRIPTION 

cpboot copies the system boot file sysboot from one directory to another. The sysboot 
file is used by the bootstrap prom to start the system, cpboot is useful for copying sys- 
boot to a floppy disk, thus making the standalone utilities (sau) directory on the floppy 
disk accessible from the boot prom. You may also use it to update a Winchester disk 
when a new software release is distributed. 

Note that you should use this command only when you want to copy sysboot to the 
entry directory of a bootable disk. In other cases, you can simply use the cp command 
to copy files. 

source directory (required) Specify directory containing the file sysboot. 

target directory (required) Specify directory to which sysboot is to be copied. This 

must be the entry directory on the target logical volume. 
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NAME 

cron - clock server 

SYNOPSIS 

/etc/cron 

DESCRIPTION 

cron executes commands at specified dates and times. Regularly scheduled commands 
can be specified according to instructions found in crontab files in the directory 
/usr/spool/cron/crontabs. You can submit your own crontab file via the crontab(l) 
command. Commands to be executed only once can be submitted by using the at( 1 ) 
command. 

cron only examines crontab files and at command files during process initialization 
and when a file changes via crontab or at. This reduces the overhead of checking for 
new or changed files at regularly scheduled intervals. 

Since cron never exits, it should be executed only once. This is done routinely through 
/etc/rc at system boot time, /us r/lib/c ron/FIFO is used as a lock file to prevent the 
execution of more than one cron. 

/usr/lib/cron/FIFO may not be removed if the previous cron process did not clean up 
nonnally. In this case, the FIFO file is still present, cron fails with a message that the 
FIFO exists. Usually, this message warns you that cron is already running, but in this 
case, you need to remove the FIFO manually. 

NOTE 

On Apollo systems, the directories /usr/lib/cron and /usr/spool/cron are both links to 
the ‘nodedata/cron directory. This separates each node’s cron area into per-node 
directories. 

FILES 

A history of all actions taken by cron are recorded in /usr/lib/cron/log. 

SEE ALSO 

at( 1 ), crontabf 1 ), sh( l ) 
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NAME 

ctnode - catalog a node in the network 
SYNOPSIS 

/etc/etnode [options] [nodejiame [net.]nodeJd ...] 

DESCRIPTION 

ctnode infonns the local node that a remote node exists, thereby enabling network file 
access to the remote node. The command catalogs the nodejiame in the local copy of 
the network root directory as the entry directory for the remote node. In other words, 
ctnode adds the directory //nodejiame to your copy of the network root directory. 



We assign a node ID to every node during the manufacturing process. To find out the 
node ID of a node, type the following command at its keyboard: 

$ lenode -me 

from another node’s network root into your own, or any other node’s network root. The 
merge options (-md and -ms) add the entry for a node to the target, provided the entry 
doe's not already exist and the source has exactly one entry for that node. In the case of 
one source and one target entry that match for a node, those entries are assumed to be 
correct. All other cases are considered to be ambiguous and the "confusion-resolution 
protocol" is invoked. 

This "confusion-resolution protocol" first attempts to verify the correct entry name with 
the node itself. If the node is available, the reply from the node is cataloged regardless 
of whether -md or —ms is used because an answer from the node itself is assumed to be 
the truth. 

If the node is unavailable to resolve an ambiguity, the entry containing the most recent 
U1D (latest time stamp portion of the UID) is used. In this case, existing entries in the 
target directory are only updated if the —ms option is used. Multiple name/ID pairs are 
permitted. 

If you do not specify -n, -update, or —from, the nodejiame and net. node Jd argu- 
ments tire required. 
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node name (optional) Specify the name of the node you wish to catalog. If the 

net. node id argument is specified, then node_name is required. 

Default if omitted: you must use — n, —update, or —from 

[net.]node_id (optional) 

Specify the hexadecimal ID (and optional network ID) of the 
node you wish to catalog. The node must be connected to the 
network when this command is executed. If the nodejxame 
argument is specified, then node jd or [net]. node jd is required. 

Default if omitted: you must use — n, —update, or —from 

Multiple name/ID pairs are permitted. 

OPTIONS 

If you do not specify — n, —update, or -from, the nodejxame and [net .\node _id argu- 
ments are required. The -n, —update, and merge options work only for remote nodes 
running Aegis SR5.0 or later. The [net.]node _id forms work only when both the local 
and remote nodes run Aegis SR9.0 or later. 

—root Catalog nodejxame as the entry directory name for nodejd in 

both the master network root directory and the local copy of the 
network root directory. This option is valid only if the 
node name and node id arguments are specified. This option is 
not valid if the — n option is specified. 

—n [net.]nodejd... Copy the entry directory name from the network root directory 

of the specified remote node to the network root directory of the 
local node. You do not need to know the entry directory name. 
However, you must specify the nodejd or the net mode jd of 
the remote node. Multiple nodejd' s and net. node jd' s may be 
specified. Use this option instead of the nodejxame 
net. node jd argument pair. This option is not valid if the — r 
option is specified. 

—update Obtain a list of nodes currently responding to a network inquiry 

and perform the same operation as — n for each node. Names 
are replaced with the most current version, if they already exist 
in your local copy of the network root directory, and new names 
are added. 
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-from I Inode ... Look in the specified list of network root directories for the 

names to add to the target network root, or use this network root 
as the source for names to merge into the target network root. 
Wildcards may be used to specify source node names. The 
-from option is not supported in a Domain internet environ- 
ment. 

This option is used with -from. Merges all names in the source 
network root into the target network root. Preference is given 
to existing names in the target if there are unresolved conflicts 
(see the discussion of "confusion-resolution protocol" above). 

This option is the same as -md, except that preference is given 
to entries in the source network root when there are unresolved 
conflicts (see the discussion of "confusion-resolution protocol" 
above). 



-on 1 Inode ... 


Catalog names in the network root of the specified nodes 
instead of the local network root. Wildcards may be used to 
specify target node names. The —on option is not supported in a 
Domain internet environment. 


-r 


Replace cataloged names if they already exist. An error occurs 
if you do not specify this option and try to add a node jiame 
that has already been cataloged (unless you are using -update). 


-1 


List node names as they are cataloged. 


-idupl 


Ignore entry (suppress error messages) if name already exists in 
the target. 


-1c 


List invocations and resolutions of the "confusion-resolution 
protocol". 


EXAMPLES 





Add the node whose ID is 21 and whose entry directory name is os to your node's cata- 
log: 



$ /etc/ctnode os 21 

Bring your node’s catalog up to date with any new nodes on the network: 
$ /etc/ctnode -update 

Copy names os and eve from the network root on //master. 

$ /etc/ctnode os eve -from //master 



-md 



-ms 
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Add node ID 21 with the name os to the network root of all nodes whose names begin 
with "a". 

$ /etc/ctnode os 21 -on //a?* 

Merge network root of os into local network root, resolving conflicts: 

$ /etc/ctnode -md -from //os 
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NAME 

ctob - catalog an object 
SYNOPSIS 

/etc/ctob pathname uid_hi.uid_low 

DESCRIPTION 

ctob assigns a pathname to an object that has a known unique identifier (U1D). ctob 
catalogs the pathname and associated UID in the naming tree. This command is pri- 
marily for system-level debugging. 

pathname (required) Specify assigned pathname. 

uidjn.uidjow (required) Specify the high and low portion of the UID as 32-bit 

hexadecimal numbers. 

EXAMPLES 

$ /etc/ctob lastfile I0A0BAAD.60000102 
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NAME 

dd — convert and copy a file 
SYNOPSIS 

dd [ option = value \ ... 

DESCRIPTION 



dd copies the specified input file to the specified output with possible conversions. The 
standard input and output are used by default. The input and output block size may be 
specified to take advantage of raw physical I/O. 


OPTIONS 

Option 


Values 




i(=file 


Input file name; standard input is the default. 




of ‘-file 


Output file name; standard output is the default. 




ibs=/t 


Input block size n bytes (the default is 512). 




obs=n 


Output block size (the default is 512). 




bs=« 


Set both input and output block size, superseding ibs and obs; 
no conversion is specified, it is particularly efficient since no 
copy is needed. 


also, if 
in-core 


ebs=/2 


Conversion buffer size. 




skip=« 


skip n Input blocks before starting copy. 




seek =22 


Seek n blocks from beginning of output file before copying. 




count=« 


Copy only n input blocks 




conv=ascii 


convert EBCDIC to ASCII 




ebedie 


convert ASCII to EBCDIC 




ibm 


Slightly different map of ASCII to EBCDIC. 




lease 


Map alphabetics to lower case. 




uease 


Map alphabetics to upper case. 




swab 


Swap every pair of bytes. 




noerror 






Do not stop processing on an error. 




sync 


Pad every input block to ibs. 





....... Several comma-separated conversions. 

When you specify sizes, dd expects a number of bytes. A number may end with k, b, 
or \v to specify multiplication by 1024, 512, or 2, respectively; a pair of numbers may 
be separated by x to indicate multiplication. 
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Use cbs only with the conv=ascii or conv=ebcdic options. If you specify conv=ascii, 
cbs characters are placed in the conversion buffer (converted to ASCII). Trailing blanks 
are trimmed and a newline added before sending the line to the output. If you specify 
conv=ebcdic„ ASCII characters are read into the conversion buffer (converted to 
EBCDIC). Blanks are added to make up an output block of size cbs. 

After completion, dd reports the number of whole and partial input and output blocks. 

DIAGNOSTICS 

f+p blocks in (out) 

Numbers of full and partial blocks read( written) 
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NAME 

df- report number of free disk blocks and i-nodes 
SYNOPSIS 

df [-It] [-f] [file-system \ directory \ mounted-resource ] 

DESCRIPTION 

df prints the number of free blocks and free i-nodes in mounted file systems, directories, 
or mounted resources by examining the counts kept in the super-blocks. 

file-system can be specified either by device name or by mount-point directory name, 
such as /usr. 

directory can be a directory name. The report presents information for the device that 
contains the directory. 

mounted-resource can be a remote resource name. The report presents information for 
the remote device that contains the resource. 

If no arguments are used, the free space on all locally and remotely mounted file sys- 
tems is printed. 

OPTIONS 

-t Causes the figures for total allocated blocks and i-nodes to be reported as well 
as the free blocks and i-nodes. 

— f Takes an actual count of the blocks in the free list, rather than taking the figure 
from the super-block (free i-nodes are not reported). This option does not print 
any information about mounted remote resources. 

NOTE 

If multiple remote resources are listed that reside on the same file system on a remote 
machine, each listing after the first one is marked with an asterisk (*). 

FILES 

/dev/dsk/* 

/elc/mnttab 

SEE ALSO 

mount(lM). 
fs(4), mnttab(4) 
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NAME 

drm_admin - Data Replication Manager Administrative Tool 

SYNOPSIS 

/etc/ncs/d r mad m i n 

DESCRIPTION 

The drmadmin tool administers servers based on the Data Replication Manager 
(DRM), such as the Global Location Broker (GLB). 

It can inspect or modify replica lists, merge databases to force convergence among 
replicas, stop servers, and delete replicas. 

The role of drm admin is to administer the replication of databases, not to change the 
data they contain. For instance, you can use drm admin to merge two replicas of the 
GLB database, but you must use Ibadmin to add a new entry to the database. Also, 
although drm admin can stop or delete a GLB replica, you must invoke glbd (the 
GLB daemon) directly if you want to start or create a replica. 

Once invoked, drm_admin enters an interactive mode, in which it accepts the com- 
mands described in the following section. 

COMMANDS 

Most drm admin commands operate on a default object (default obj) at a default host 
(default _host). Together, default _obj and default host specify a default replica. 
Defaults are established by the set command and are remembered until changed by 
another set. 

Currently, the only known object is gib. 

Some drm_admin commands operate on a host other than the default; we identify this 
host as other host. The host name you supply as a default host or an other _host takes 
the form family'.host. The only currently supported family is dds; you can specify a 
host in this family by its entry directory or by its network address. For example, 
dds:/7thurber and (Ids:# 1 234. abed are acceptable host names. 

addrep other host Add other Jiost to the replica list at default Jiost. The replica at 
default host will propagate other host to all other replica lists for 
default _ohj. 

del rep other _host [ -force ] 

Delete the replica of default oh j at other Jiost. 

The del rep command tells the replica at other host 

1 . To propagate all of the entries in its propagation queue 

2. To propagate a delete request to all other replicas, causing 
other Jiost to be deleted from all other replica lists for 
default _obj 
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3. To delete its copy of default _obj 

4. To stop running 

The -force option causes a more drastic delete. It deletes other host from the replica 
list at default Jiost. The replica at default Jiost propagates the delete request to the 
replicas at the hosts remaining on its list, thereby removing other Jiost from all other 
replica lists for default _obj. 

A force delete can cause data to be lost and should only be used when a replica has irre- 
vocably "died." We recommend strongly that you do a mergeall operation after the 
force delete to prevent the remaining replicas of the default _obj database from becom- 
ing inconsistent. If the deleted replica is still running, it should be reset. 

info Get status information about the replica for default _obj at 

default Jiost. 

Irep [ -d ] l —clocks ] [ -na ] 

List replicas for default_obj as stored in the replica list at 

default Jiost. 

The -d option lists deleted as well as existing replicas. 

The -clocks option shows the current time on each host and indi- 
cates clock skew among the replicas. 

The -na option lists the network address of each host. 

merge { -from | -to } other host 

The merge command copies entries in the default _obj database 
and replica list from one replica to another. It copies an entry if 
no corresponding entry exists in the destination database or if the 
corresponding entry in the destination database bears an earlier 
time stamp. 

A merge does not cause entries to be propagated. The database 
and replica list at the origination are not changed. 

The -from option copies entries from the default _obj database 
and replica list at other Jiost to the default _obj database and 
replica list at default Jiost. 

The —to option copies entries from the database and replica list at 
default Jiost to the database and replica list at other Jiost. 

A merge -from followed by a merge -to causes the replicas at 
the two hosts to converge. 
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merge_all The merge_all command uses default Jiost as the hub for a glo- 

bal merge of all replicas for default obj. A merge_all first does 
a merge —from each host on default Jiost' s replica list; then it 
does a merge -to each host on the replica list. All replicas of 
default _obj are thereby forced into a consistent state. 

A merge all should be used 

• When a replica is force deleted 

• When a replica is reset 

• When a replica has been incommunicado for 2 weeks or more 

• When a replica "dies" (for example, when its database is des- 
troyed by a disk failure). The merge_all operation does not 
cause any entries to be propagated. 

This command causes drm_admin to read the clock of each 
replica of the default _obj every n minutes and to report any clock 
skews or non-answering replicas. If you do not specify — r, The 
period is 15 minutes. 

Quit the drmadmin session. 

Replace the network address for other host in the replica list at 
default Jiost. The replica at default host will propagate the new 
entry for other Jiost to all other replica lists for default obj. Use 
reprep only when a host’s network number changes. 

Reset the replica of default obj at other host. 

The reset command tells the replica at other Jiost to delete its 
copy of default _obj and to stop running. It does not cause 
other host to be deleted from any other replica lists. This com- 
mand can cause data to be lost unless a successful nierge_all is 
done first. 

set [ -o obj name ] -h hostjiame 

Set the default object and host. Subsequent commands that do 
not specify a host will be sent to this host. All subsequent com- 
mands will operate on the object objjiame. If you do not specify 
the — o option, drm_admin keeps the current default _obj. 

If you use set with the -o option, drm admin checks the clocks 
at all hosts with replicas of the specified object. 

stop Stop the server for default_obj that is running at default Jiost. 



monitor [ -r n \ 
quit 

reprep other Jiost 
reset other host 
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EXAMPLES 

Start drm_admin, set the default object to gib, and set the default host to //mars: 
$ /etc/ncs/drm_admin 

drm_admin: set -o gib -h dds://mars 

Default object: gib default host: dds://mars 

state: in service 
Checking clocks of gib replicas 
dds : / /mars 1987/04/09.17:09 
dds : / /pluto 1987/04/09.17:09 
dds: //mercuryl 987/04/09. 17 : 07 



SEE ALSO 

glbd(lM), lb_admin(lm) 

Managing the NCS Location Broker. 
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NAME 

dtcb - dump contents of tcp control blocks 

SYNOPSIS 

/etc/ dtcb [— f] [[— t] 

[<tcb addr> |-a ] |-u 
[<ucb_addr> | -a ]] 

DESCRIPTION 

The command dtcb dumps the contents of the tcp control blocks associated with a par- 
ticular tcp connection. The address of the tcb to be dumped may be obtained using the 
netstat program. Two control blocks are dumped: the ucb (user control block) which 
contains the send and receive queues and user-related flags, and the tcb (tcp control 
block) which contains the connection sequence numbers, state, flags, and out-of- 
sequence queues. 

OPTIONS 
-f 

-t <tcb_addr> 

-u <ucb_addr> 

-a 

EXAMPLES 

The dump of a tcp control block for a listening ftp connection might look like this: 

$ /etc/dtcb -t 1A9A50 

ucb at 0xlA99C4: 
local 0.0. 0.0 lport 21 
host 0 . 0 . 0 . 0 fport 0 

uc_snd 8192 uc_ssize 0 uc_rcv 8192 uc__rsize 0 
uc_shead 0 uc_stail 0 uc_rhead 0 uc_rtail 0 
:-:f lag : 

UREUSEADDR UCANACCEPT 
iost ate : 

status : 

UCLOSED 
flags : 

UTCP 

oobmark 0 oobcnt 0 



Force output if tcpd not running. 

Hexadecimal address of a tcb or, if not supplied, all tcbs. 
Hexadecimal address of a ucb or, if not supplied, all ucbs. 
All (both tcb’s and ucb’s for each socket). 
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TCB at 0xlA9A50: 
lport 0x0 fport 0x0 
t_st ate LISTEN 

irs 00000000 rcv_urp 00000000 rcv_urg 00000000 rev nxt 
rcv_end 00000000 

iss 1E3202D4 seq_fin 1E3202D4 snd_end 1E3202D4 
snd_urp 00000000 snd_lst 00000000 

snd_nxt 1E3202D4 snd_una 1E3202D4 snd_wl 00000000 

snd_hi 1E3202D4 

rex_val 00000000 rtl_val 00000000 xmt_val 00000000 
flags : 

snd_wnd 0 max s eg 0 xmtime 2 rxtet 0 
timers : 

INIT 0 REXMT 0 REXMTTL 0 PERSIST 0 FINACK 0 
t_rcv_next 1A9A50 t_rcv_prev 1A9A50 



00000000 
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NAME 

du - summarize disk usage 
SYNOPSIS 

du [ -sar ] [ names ] 

DESCRIPTION 

du reports the number of blocks contained in all files, and recursively, directories 
within each file and directory specified by the names argument. The block count 
includes the indirect blocks of the file. If names is missing, the current directory is 
used. 

OPTIONS 

— s Causes only the grand total (for each of the specified names) to be given. 

—a Causes an output line to be generated for each file. 

— r Causes messages to be generated about directories that cannot be be read, files 

that cannot be opened, etc., rather than being silent (the default). 

NOTES 

If neither -s nor -a is specified, an output line is generated for each directory only. 

A file with two or more links is counted only once. 

BUGS 

If the —a option is not used, non-directories given as arguments are not listed. 

If there are links between files in different directories where the directories are on 
separate branches of the file system hierarchy, du counts the excess files more than 
once. 

Files with holes get an incorrect block count. 
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NAME 

edmtdesc - edit magtape descriptor file 
SYNOPSIS 

/etc/edmtdesc {options } pathname 
DESCRIPTION 

edmtdesc allows you to create, list, and modify magnetic tape descriptor objects. 
These descriptor files provide information to the streams manager so that it can handle 
subsequent tape operations much as an sio descriptor file describes the configuration of 
an sio line. 

pathname (required) Specify name of magtape descriptor file to be created, listed, or 

edited. 



OPTIONS 

At least one of the following options must be specified. 

-c Create a new magtape descriptor object with the name given in 

the pathname argument. 

—I [ var ...] List the values of the variable(s) specified. If no variables are 

named, the entire magtape descriptor is listed. 

— s [var value]... Set the variable(s) indicated to the specified value(s). At least 

one variable/value pair is required if -s is specified. Multiple 
variable/value pairs are permitted, separated by blanks. 

VARIABLES 

The variables known to edmtdesc are listed below, along with their types and default 

values. The variable types are: integer (int), Boolean (y/n), character string of n letters 

(c [«]), and date (in format yy/mm/dd.hh:mm). 



Name 


Type 


Default 


Definition 


dev 


c[l] 


m 


device type (’m’ for magtape, ’c' for car- 
tridge) 


u 


int 


0 


magtape unit number (normally 0) 


lab 


y/n 


yes 


’yes’ if magtape is ANSI labeled, ’no’ if 
unlabeled 


reo 


y/n 


no 


’yes’ to reopen previously used volume, ’no’ 
to open new volume (’yes’ suppresses 
rewind) 


civ 


y/n 


yes 


’yes’ closes volume when file is closed, ’no’ 
leaves volume open 
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Name 


Type 


Default 


Definition 


spos 


y/n 


no 


’yes’ saves volume position when volume is 
closed (for reopen), ’no’ rewinds volume 
when closed 


vid 


c[6] 


-auto 


volume identifier (labeled volumes) 


vacc 


c[l] 




volume accessibility (labeled volumes) 


own 


c[ 14] 


-auto 


volume owner (labeled volumes) 


f 


int* 


1 


file sequence number: integer or "cur" for 
current file, or "end" for new file at end of 
labeled volume 


rf 


c[l] 


D 


record format — "f for fixed length, "d" for 
variable length, "s" for spanned, "u" for 
undefined 


bl 


int 


2048 


block length, in bytes 


rl 


int 


2048 


(maximum) record length, in bytes 


ascnl 


y/n 


yes 


’yes’ for ascii newline handling (strip new- 
lines on write, supply them on read), ’no’ 
for no newline handling 


fsect 


int 


1 


file section number (labeled volumes) 


fid 


c[171 




file identifier (labeled volumes) 


fsid 


c[6] 




file set identifier (labeled volumes) 


gen 


int 


1 


generation of file (labeled volumes) 


genv 


int 


1 


generation version of file (labeled volumes) 


cdate 


date 


-auto 


creation date of file (labeled volumes) 


edate 


date 


-auto 


expiration date of file (labeled volumes) 


face 


c[l] 




file accessibility (labeled volumes) 


sysc 


c[xx] 




system code (labeled volumes) 


sysu 


c[xx] 




system use (labeled volumes) 


boff 


int 


0 


buffer offset (labeled volumes, should be 0) 



For cartridge tape (dev c), you must change the block length (hi) and the record length 
(rl) to be 512 or less and the record format to be fixed (rf f). 

EXAMPLES 

Edit file set_tape; set the tape unit number to 1; declare tape as ANSI labeled. 

$ /etc/edmtdesc set_tape -s u I lab yes 

Create descriptor file ct for cartridge tape, blocking 4 records of maximum length 128 
to each block. 

$ /etc/edmtdesc ct -c -s dev c bl 512 rl 128 rf f 
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NAME ' ■' 

edns - invoke editor for nshelper 
SYNOPSIS 

/etc/edns [[net .]node _id\ 

DESCRIPTION 

edns allows you to inspect and/or modify ns_helper’s master network root directory 
and replica list. Once invoked, edns enters an interactive mode and accepts the com- 
mands described in help edns commands. 

[net.\node_id (optional) Set the default ns_helper to the ns_helper at the node 

specified by the internet address. 

Default if omitted: Set the default ns_helper to any active 

ns_helper. An ns_helper becomes 
active after its database has been initial- 
ized. 
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NAME 

/etc/edrgy - edit the network registry database 
SYNOPSIS 

/etc/edrgy [ —a | — p | — g | — o ] [ — I ] [ -s llsite ] [ -synch ] [ — v ] 

DESCRIPTION 

The edrgy tool views and edits information in the registry database. You can invoke 
edrgy from any node. 

Though anyone can read information in the registry database, you can usually change 
information only if you own the affected database entries. For example, only the owner 
of a group can add a name to the group’s membership list. 

With edrgy, you can edit and view names, accounts, and policies in the network regis- 
try, as well as entries in the local registry. The tool operates in one of four domains: 
person names, group names, organization names, and accounts. 

OPTIONS 

You can specify only one of —a, -p, — g, and — o. 



-a (default) 


Edit or view accounts. 


-P 


Edit or view persons. 


-g 


Edit or view groups. 


-o 


Edit or view organizations. 


-1 


Edit or view entries in local registry. 


-s 


Use the specified registry site. 


-synch 


Synchronize local registry with network registry. 


— V 


View selected entries. 



Unless you specify the — v option, edrgy operates interactively. The following sections 
describes the commands you can enter in the interactive mode. 

COMMANDS FOR PERSONS, GROUPS, AND ORGANIZATIONS 
v[ie\\ | [ name | number ][-!'][ -ni ] [ -po ] 

View name entries. 

If you specify a number, edrgy displays all matching entries, including 
any aliases. 

The — f option displays entries in full (all fields except the membership 
list and organization policy). 

If you are viewing groups or organizations, -m displays the membership 
list. For persons, -m lists all groups of which the person is a member, 
including groups that cannot appear in a project list. 
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If you specify — po while viewing organizations, edrgy displays policy 
information. Otherwise, it shows only the name and the UNIX number. 

a[dd] [ person number [fullname ] [ — al ] [ -o owner ] ] 

a[dd] [ group number [fullname [ password ] ] [ — nl ] [ — o owner ] ] 

a[dd] [ organization number [fullname [ password ] ] [ -o owner ] ] 

Create a new name entry. 

If you do not specify a person, group, or organization name, the add 
command enters an interactive mode and prompts you for each field in 
the entry. If you are adding organizations in the interactive mode, the 
command prompts you for policy infonnation as well. 

Specify the owner as a person.group.organization triplet. You can use 
% as a wildcard for any or all of the components. If you do not use the 
— o option, edrgy assigns the default owner, which you can set or display 
with the defaults command. 

For persons, the — al option creates an alias entry. If number (the UNIX 
number) is already assigned to a person and you do not specify — al, an 
error occurs and you must either choose a different number or specify 
— al. If you use — al to create an alias and number is not already associ- 
ated with a primary name, edrgy issues a warning but creates the alias. 

For groups, the -nl flag indicates that the group is not to be included on 
project lists; omitting this flag allows the group to appear on project lists. 

For groups and organizations, a space between quotation marks indicates 
a nil password. 

Use quotation marks to embed spaces (or quotation marks) in a fullname. 
A single space between quotation marks indicates a nil fullname. 



c[hange] [ person [ -n name ] [ — u number ] [ — f fullname ] [ -o owner ] 

[ -al | -pr ] ] 

e[liange] [ group [ -n name ] [ -u number ] [ -f fullname ] [ -o owner ] 

[ -p password ] [ — nl | — I J J 

cfhange] [ organization [ -n name ] [ -u number ] [ — f fullname ] [ — o owner ] 

[ -p password ] ] 

Change a name entry. 

If you do not specify a person, group, or organization name, the change 
command enters an interactive mode and prompts you for a name. If 
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you do not specify any fields, the command prompts you for each field in 
succession. To leave a field unchanged, press <RETURN> at the 
prompt. If you are changing organization entries in the interactive mode, 
the command prompts you for policy information as well. 

For person entries, the — al flag changes a primary name into an alias, 
while the -pr flag changes an alias into a primary name. This change 
can be made only from the command line, not in the interactive mode. 

For group entries, the — nl flag disallows the group from appearing in 
project lists, while the -1 flag allows the group to appear in project lists. 

For organization entries, you can change policy information only in the 
interactive mode. 

A single space between quotation marks indicates a nil fullname or pass- 
word. 

Specify the owner as a per son.gr oup. organization triplet. You can use 
% as a wildcard for any or all of the components. 

Changes to a person name are reflected in membership lists that contain 
the person name. For example, if the person ludwig is a member of the 
group composers and the person name is changed to louis, the member- 
ship list for composers is automatically changed to include louis but not 
ludwig. 



Changes to number (the UNIX number) cause the operating system to 
change its mapping of the UID, the primary name, and any aliases from 
the old number to the new one. However, files owned by the old number 
do not automatically show the new number as their owner. 

The only fields of reserved entries that you can change are the fullname, 
the password, the owner, and (for groups) the property that allows a 
group to appear in project lists. If a reserved group is allowed to appear 
in project lists, you can disallow it; but if the group is disallowed, you 
cannot allow it. 

ni[ember] [ group \ organization [ —a member Jist ] [— r member list ] ] 

Edit the membership list for a group or organization. 

If you do not specify a group or organization, the member command 
enters an interactive mode and prompts you for names to add or remove. 
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The -a flag precedes the person names (separated by spaces) to be added 
to the membership list, while the — r flag precedes those to be removed. 
If you do not include either flag on the command line, edrgv prompts 
you for names to add or remove. 

Adding a person to a membership list permits creation of a login account 
for that person with that group or organization. 

Removing person from the membership list for group has the side effect 
of deleting all login accounts of the form person.group, and likewise for 
organizations. 

del[ete] { person \ group \ organization } 

Delete a name entry. 

You cannot delete reserved names. Deleting a group or organization has 
the side effect of deleting any accounts with that group or organization. 

adopt uidhigh.uidjow person number [fullname ] [ -o owner ] 

adopt uid high.uidjow group number [ password [fullname ] ] [ -nl ] [ -o owner] 

adopt uid high.uidjow organization number [ password [ fullname ] ] [ — o owner] 

Create a primary name entry for the specified UID. 

The UID must be an orphan (a UID for which no name exists in any 
domain). The uid high and uidjow are hexadecimal numbers. 

An error occurs if you specify a name or UNIX number that is already 
defined within the same domain of the database. 

A single space between quotation marks indicates a nil fullname or pass- 
word. 

Specify the owner as a person.group. organization triplet. You can use 
% as a wildcard for any or all of the components. If you do not use the 
-o option, edrgv assigns the default owner , which you can set or display 
with the defaults command. 

COMMANDS FOR ACCOUNTS 

In all of the account operations, the account argument is a person.group.organization 
triplet such as jones.graphics.research. Unless otherwise specified, any or all of the 
components can be the wildcard character, %. For example, view % .(lev. % views all 
accounts associated with the group dev. 

In an account argument, if you omit a trailing organization (or group.organization), % 
(or %.%) is assumed. Thus, keats.%.%, keats.%, and keats are equivalent. 
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v[ie\v] [ account | [ — f] 

Display login accounts specified by the account pgo (person, group, 
organization) triplet. 

Without the -f flag, view displays only the user fields in each account 
entry: abbreviated account S encrypted password, miscellaneous infor- 
mation, home directory, and login shell. 

With — f, view displays the full entry, including the administrative fields 
as well as the user fields. Administrative information includes who 
created the account, when it was created, who last changed it, when it 
was last changed, when it expires, whether it is valid, whether the pass- 
word is valid, and when the password was last changed. 

a[dd] [ account [ — a { p | pg | pgo } ] [ password [ mi sc [ homedir [ shell ] ] ] j 
[ — pnv ] [ -\ account exp | none] [ -anv ] ] 

Create a login account. 

Specify account as a pgo triplet. Wildcards are not allowed. If you do 
not supply an account on the command line, add enters an interactive 
mode and prompts you for each field in succession. 

If the person specified in account is not already a member of the 
specified group and/or organization, edrgy automatically attempts to add 
the person to the membership lists. If you are not an owner of the group 
and/or organization, the attempt will fail and the account will not be 
created. 

The -a flag indicates the degree of abbreviation allowed for login: p 
means that only the person is required; pg means the person and the 
group; pgo means that all three components of the account SID are 
required. (Of course, a user can always supply more components than 
are required.) If the abbreviation you specify is already defined for 
another account, edrgy automatically uses the shortest unique abbrevia- 
tion and issues a warning. 

For example, if you create an account babar.elephnnts.none with the 
abbreviation p, a user need only enter babar at the login prompt to use 
the account. If you then create an account babar. kings.none, the p 
abbreviation will conflict with the existing account, so the pg abbrevia- 
tion, baba r. kings, will be the shortest unique one. 

Omitting the —a is equivalent to specifying -a p and results in use of the 
shortest unique abbreviation. 
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The password must adhere to the policy of the associated organization or 
the policy of the registry as a whole, whichever is more restrictive. 

The misc field is not used by the operating system. The gecos field of 
each account’s entry in the /etc/passwd file is the concatenation of the 
person’s full name and the account’s misc. Use quotes to include spaces, 
hyphens, or quotes in misc. 

The homedir and shell are pathnames. The default homedir is /. The 
default shell is the null string. 

Use a single space between quotation marks to indicate a nil password, 
miscjnfo, homedir, or shell. 

The — pnv (password not valid) flag specifies that at the next login (for a 
newly created account, the first login), the user must change the pass- 
word. If you omit this option, the password is valid. 

The -x flag sets an expiration date for the account; the default is none. 

The — anv (account not valid) flag specifies that the account is not 
currently valid for login. If you omit this option, the account is valid. 

c[hange] [ account [ -n new _account ] [ -a { p | pg | pgo } ] 

[ -p password ] [ -m misc ] [ -h homedir ] [ -s shell ] 

[ -pnv | — pv ] [ -x account exp | none] [ -anv | -av ] 

Change one or more account entries. 

Specify account as a pgo triplet. Wildcards are allowed, unless you use 
the — n option. If you do not supply an account on the command line, 
change enters an interactive mode and prompts you for each field in suc- 
cession. Press <RETURN> to leave a field unchanged. 

The command line arguments are largely the same as those of the add 
command. The — n flag enables you to change the account SID to 
new_account, a pgo triplet that cannot contain wildcards. The -pv flag 
specifies that the password is valid. The — av flag specifies that the 
account is valid. 

You can enter a single space between quotation marks to indicate a nil 
password, misc, homedir or shell. 
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delfete] account 

Delete the entry for account, a pgo triplet that cannot contain wildcards. 

MISCELLANEOUS COMMANDS 
dofmain] [ p | g | o | a ] 

Change or display the type of registry information being viewed or 
edited. 

You can specify p for persons, g for groups, o for organizations, or a for 
accounts. If you supply no argument, edrgy displays the current 
domain. 

s[ite] [ 1 1 site ] [ -I ] 

Change or display the registry site being viewed or edited. 

If you specify a II site, edrgy attempts to use the registry server at the 
named site. If you specify -I, edrgy uses the local registry. If you sup- 
ply no argument, edrgy displays the current site. 

properties] 

Change and/or display the registry properties and policies. 

This command prompts you for any changes to make. Press 
<RETURN> to leave information unchanged. 

synch[ronize] 

Update the local registry to match the master registry. 

If a matching entry cannot be retrieved from the network registry, the 
local entry is marked invalid for login, and its UNIX numbers are 
updated. 

co[py] [ account ] 

Copy information for the specified accounts from the master registry to 
the local registry. 

The account is a pgo triplet that can contain wildcards; trailing wildcard 
components can be omitted. If a matching account already exists in the 
local registry, edrgy updates the information to match that in the master 
registry; otherwise, edrgy adds the entry. If all entries in the local regis- 
try are used, copy reports an error and terminates. 

defaults] 

Change and/or display the default values that edrgy uses. 
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h[elp] [ command ] 

Display usage information for edrgy. 

If you do not specify a particular command, edrgy lists the available 
commands. 

q[uit] Exit edrgy. 

COMMANDS VALID FOR THE LOCAL REGISTRY 

To edit or view the local registry, use the -1 flag when you invoke edrgy. This section 
lists the commands that are valid for editing or viewing the local registry. Unless other- 
wise specified, all options are as described in the previous command descriptions. 

v[iew] [ name \ number J [ — f ] [ -po ] 

View name entries. (The -m option is not valid.) 

v[iew j [ account ] [ — f] 

Display specified login accounts. 

c[hange] [ account [ — a { p | pg | pgo } ] [ — m mi sc J [ -h homedir ] [ —any j 

Change one or more account entries. (The — p, — s, — pnv, — pv, — x, and 
— av options are not valid.) 

del [ete| account 

Delete an account entry. 

do[mainl [ p | g | o | a ] 

Change or display the type of registry information being viewed or 
edited. 

s[ite] [ II site ] [ -I ] 

Change or display the registry site being viewed or edited. 

properties] 

Change and/or display the registry properties and policies. 

synch [roni/.e] 

Update the local registry to match the master registry. 
co[py] [ account ] 

Copy information for the specified accounts from the master registry to 
the local registry. 

def[auits] 

Change and/or display the default values that edrgy uses. 

h[elp] [ command ] 

Display usage information for edrgy. 

q[uit] Exit edrgy. 
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NAME 

environment - inquire about system environment 
SYNOPSIS 

/etc/environment [-cj [ — i] 

DESCRIPTION 

This command is used by shell scripts to inquire about the current "environment", 
installed environments, or both. 

OPTIONS 

If no flags are specified, the current environment is printed. If — i is specified, however, 
and you also want current environment, you must add —c. 

— c print current environment 

— i print installed environments 

EXAMPLES 

$ /etc/environment 

aegis 

$ /etc/environment -c 

aegis 

$ /etc/environment -i 

aegis sysv bsd 
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NAME 

find_orphans - locate and catalog uncataloged objects 
SYNOPSIS 

/etc/find_orphans [ options ] [volume _pathname ] 

DESCRIPTION 

tind orphans finds all uncataloged permanent objects in a local volume. It uses or 
creates a directory "lost+found" in the root of the volume and creates entries for all 
objects not cataloged elsewhere. 

find_orp3ians can operate by itself by using search mode, in which case it searches the 
volume for all orphans, or it works with salvol (list mode, the default), in which case it 
just catalogs the orphans detected by the previous run of salvol. Both methods find 
exactly the same set of orphans. We recommend that you run find_orphans every time 
a node is booted, and on every mounted volume. Below is a description of the two 
modes of operation. 

The objects cataloged by find_orphans are given sequential names like fl, f2, etc., and 
you can move them using /com/m vf or /bin/mv to a directory of your choice. 
tind_orphans is useful for finding objects that were being updated during a system 
crash or that were uncataloged through program errors. 

In list mode (the default), find_orphans catalogs all objects listed in the file 
lost+found.list in the entry directory of the volume. If the file does not exist, 
lind_orphans creates it. Note that invol creates the file when it creates the volume. If 
the lost+found.list exists, salvol enters information describing each orphan. List mode 
is considerably faster than search mode since there is no need to search the entire 
volume. You must have permission to catalog objects in lost+found. 

In search mode, you must have read permission to all directories on the volume. If 
some directory is not readable, every object under that directory is cataloged in the 
lost+found directory. In addition, you must have permission either to create the 
lost+found directory or to catalog objects in lost+found when it already exists. 
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Search mode should be run only on a quiescent node; that is, one not connected to the 
network (use netsvc — n to disable network communications) and not actively running 
any processes other than the one performing the find orphans operation. 

volume _pathname (optional) 

Specify the name of the volume to be searched. The volume must be 
physically attached to your node; you may not find orphan objects 
on volumes elsewhere in the network. 



Default if omitted: search node boot volume 



OPTIONS 

— I [ist] (default) List mode, catalog objects listed in /lost+found.list. 

— s[earch] Search mode, search the volume for orphans. 

— v[erifv] Verify only; don’t catalog any orphans. 

EXAMPLES 

$ /etc/find_orphans 

Cataloging in: /lost+found 

39D40FF0 . 100086CA -> fl 

39D40F9D .E00086CA -> f2 

39D41026. 600086CA -> f3 

39D40DA6 .D00086CA -> f4 

39D40998 . 200086CA -> f5 

39D41042 . 800086CA -> f6 

39D40CB8 .E00086CA -> f7 

39D41001 . 300086CA -> f8 

39D40F7E .D00086CA -> f9 

39D40CCE . F00086CA -> flO 

39D40D8B .C00086CA -> fll 

39D40E33 . 100086CA -> fl2 

39D40A06 . 700086CA -> fl3 

39D40F23 . 900086CA -> fl4 

39D40E1 6 . 000086CA -> fl5 

39D40F36 .A00086CA -> fl6 

39D41C0A. 200086CA -> fl7 

Number of orphans catalogued: 17 
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$ Id -a /lost+found 



Directory "/lost+found": 



sys 

type 


type 

uid 


blocks 

used 


current 

length 


attr 


rights 


name 


file 


uasc 


1 


32 


P 


prwx- 


fl 


file 


unstruct 


0 


0 


P 


prwx- 


f 10 


file 


uasc 


1 


32 


P 


prwx- 


fll 


file 


unstruct 


0 


0 


P 


prwx- 


f 12 


file 


unstruct 


1 


54 


P 


prwx- 


f 13 


file 


uasc 


1 


32 


P 


prwx- 


f 1 4 


file 


uasc 


1 


32 


P 


prwx- 


f 15 


file 


unstruct 


0 


0 


P 


prwx- 


f 1 6 


file 


unstruct 


0 


0 


P 


prwx- 


f 17 


file 


unstruct 


0 


0 


P 


prwx- 


f 2 


file 


uasc 


1 


32 


P 


prwx- 


f 3 


file 


unstruct 


0 


0 


P 


prwx- 


f 4 


file 


cof f 


1 


101376 


P 


prwx- 


f 5 


file 


unstruct 


0 


0 


P 


prwx- 


f 6 


file 


uasc 


1 


32 


P 


prwx- 


fl 


file 


unstruct 


0 


0 


P 


prwx- 


f 8 


file 


uasc 


1 


32 


P 


prwx- 


f 9 



17 entries, 9 blocks used. 
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NAME 

ftpd - DARPA Internet File Transfer Protocol server 
SYNOPSIS 



/etc/ft pd [ 


-d ] [ — 1 ] [ —{timeout ] 


DESCRIPTION 




ftpd is the DARPA Internet File Transfer Protocol server process. The server uses the 
TCP protocol and listens at the port specified in the “ftp” service specification; see ser- 


vices(4). 




OPTIONS 




-d 


Write debugging information to the syslog. 


-1 


Log each ftp session in the syslog. 


- {timeout 


Set the inactivity timeout period to timeout. Without this option, the ftp 
server will timeout an inactive session after 15 minutes. 


FTP REQUESTS 




The ftp server currently supports the following ftp requests; case is not distinguished. 


Request 


Description 


ABOR 


Abort previous command 


ACCT 


Specify account (ignored) 


ALLO 


Allocate storage (vacuously) 


APPE 


append to a file 


CDUP 


Change to parent of current working directory 


CWD 


Change working directory 


DELE 


Delete a file 


HELP 


Give help information 


LIST 


List files in a directory (“Is -Ig”) 


MKD 


Make a directory 


MODE 


Specify data transfer mode 


NLST 


Give name list of files in directory (“Is”) 


NOOP 


Do nothing 


PASS 


Specify password 


PASV 


Prepare for server-to-server transfer 


PORT 


Specify data connection port 


PWD 


Print the current working directory 


QUIT 


Terminate session 


RETR 


Retrieve a file 


RMD 


Remove a directory 


RNFR 


Specify rename-from filename 


RNTO 


Specify rename-to filename 


STOR 


Store a file 


STOU 


Store a file with a unique name 


STRU 


Specify data transfer structure 
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TYPE Specify data transfer type 

USER Specify username 

XCUP Change to parent of current working directory 
XCWD Change working directory 

XMKD Make a directory 

XPWD Print the current working directory 

XRMD Remove a directory 

The remaining ftp requests specified in Internet RFC 959 are recognized, but not imple- 
mented. 

The ftp server will abort an active file transfer only when the ABOR command is pre- 
ceded by a Telnet "Interrupt Process" (IP) signal and a Telnet "Synch" signal in the 
command Telnet stream, as described in Internet RFC 959. 

ftpd interprets filenames according to the “globbing” conventions used by csh(l). 
This allows users to utilize the metacharacters “*?[J{ }~”. 

ftpd authenticates users according to four rules. 

1) The username must be in the password data base, /etc/passvvd, and not have a 
null password. In this case a password must be provided by the client before 
any file operations may be performed. 

2) The username must not appear in the file /etc/ftpusers. 

3) The user must have a standard shell returned by getusershell( ). 

4) If the username is “anonymous” or “ftp”, an anonymous ftp account must be 
present in the password file (user “ftp”). In this case the user is allowed to log 
in by specifying any password (by convention this is given as the client host’s 
name). 

In the last case, ftpd takes special measures to restrict the client’s access privileges. 
The server performs a ehroot(2) command to the home directory of the “ftp” user. In 
order that system security is not breached, we recommend that the “ftp” subtree be 
constructed with care; the following rules are recommended. 

ftp Make the home directory owned by “ftp” and unwritable by anyone. 

"ftp/bin Make this directory owned by the super-user and unwritable by anyone. 

The program ls(l) must be present to support the list commands. This 
program should have mode 111. 

'ftp/etc Make this directory owned by the super-user and unwritable by anyone. 

The files pass\vd(4) and group(4) must be present for the Is command to 
work properly. These files should be mode 444. 

'ftp/pub Make this directory mode 777 and owned by “ftp”. Users should then 
place files which are to be accessible via the anonymous account in this 
directory. 
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BUGS 

The anonymous account is inherently dangerous and should be avoided when possible. 

The server must run as the super-user to create sockets with privileged port numbers. It 
maintains an effective user id of the logged in user, reverting to the super-user only 
when binding addresses to sockets. The possible security holes have been extensively 
scrutinized, but are possibly incomplete. 

SEE ALSO 

ftp(lC), syslogd(lM); 

Configuring and Managing TCP/IP. 
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NAME 

gencc - create a front end to the cc command 

SYNOPSIS 

gencc 

DESCRIPTION 

gencc is an interactive command that helps create a front end to the cc command. The 
cc command has default loations for the preprocessor, compiler, and linker, but it is 
possible to specify new locations of those tools without requiring a new cc command. 
Specify these new locations of moved pieces by using the — Y option to the cc com- 
mand. However, it is inconvenient to supply the proper — Y options with every invoca- 
tion of cc. Also, if a system administrator moves those tools, this movement should be 
invisible to users. 

The front end to the cc command that gencc generates is a one-line shell script that calls 
cc with these — Y options specified. This front end also passes all options that you sup- 
ply to the cc command. 

gencc works by prompting you for the location of each tool and directory that can be 
respecified by a -Y option to cc. If you do not specify a location, it assumes that that 
tool has not been relocated. After all the locations have been prompted for, gencc 
creates the front end to cc in the current working directory and gives the file the same 
name as the cc command. Therefore, you cannot run gencc in the same directory that 
contains the actual cc command. Also, if a system administrator has redistributed the 
tools, you should place the actual cc command somewhere that is not typically in a 
user’s PATH (e g., /lib). This prevents you from accidentally invoking cc without 
using the front end. 

CAVEATS 

gencc does not produce warnings if a tool or director}' does not exist at the specified 
location. Also, gencc does not actually move any files to new locations. 

FILES 

./cc Front end to cc 

SEE ALSO 

cc(l). 
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NAME 

gettable - get NIC format host tables from a host 
SYNOPSIS 

/etc/gettable [ -v ] host [ outfile ] 

DESCRIPTION 

gettable is a simple program used to obtain the NIC standard host tables from a “nic- 
name” server. The indicated host is queried for the tables. The tables, if retrieved, are 
placed in the file outfile or by default, hosts.txt. 

gettable operates by opening a TCP connection to the port indicated in the service 
specification for “nicname”. A request is then made for “ALL” names and the resul- 
tant information is placed in the output file. 

gettable is best used in conjunction with the htable(lM) program which converts the 
NIC standard file format to that used by the network library lookup routines. 

OPTIONS 

— v Get just the version number instead of the complete host table, and puts 

the output in the file outfile or by default, hosts. ver. 

outfile Place the tables in the specified outfile. 

BUGS 

If the name-domain system provided network name mapping well as host name map- 
ping, gettable would no longer be needed. 

SEE ALSO 

intro(3N), htable(lM), named(lM); 

Configuring and Managing TCP/IP. 
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NAME 

getty - set terminal mode 
SYNOPSIS 

/etc/ getty [ type [ tty ] ] 

DESCRIPTION 

gctty is usually invoked by init(8) to open and initialize the tty line, read a login name, 
and invoke login(l). getty attempts to adapt the system to the speed and type of termi- 
nal being used. 

The argument tty is the special device file in /dev to open for the terminal (for example, 
ttyhO). If there is no argument or the argument is a dash (-), the tty line is assumed to 
be open as file descriptor 0. 

The type argument can be used to make getty treat the terminal line specially. This 
argument is used as an index into the gettytab(5) database, to determine the charac- 
teristics of the line. If there is no argument, or there is no such table, the default table is 
used. If there is no /etc/ getty tab a set of system defaults is used. If indicated by the 
table located, getty will clear the terminal screen, print a banner heading, and prompt 
for a login name. Usually either the banner or the login prompt will include the system 
hostname. Then the user’s name is read, one character at a time. If a null character is 
received, it is assumed to be the result of the user typing the break (interrupt) character. 
The speed is usually then changed and the login prompt is typed again; a second 
“break” changes the speed again and the login prompt is typed once more. Successive 
break characters cycle through the same standard set of speeds. 

The user’s name is terminated by a newline or carriage-return character. The latter 
results in the system being set to treat carriage returns appropriately (see tty(4)). 

The user’s name is scanned to see if it contains any lower-case alphabetic characters; if 
not, and if the name is nonempty, the system is told to map any future upper-case char- 
acters into the corresponding lower-case characters. 

Finally, login is called with the user’s name as an argument. 

Most of the default actions of getty can be circumvented, or modified, by a suitable get- 
tytab table. 

getty can be set to timeout after some interval, which will cause dial up lines to hang up 
if the login name is not entered reasonably quickly. 

DIAGNOSTICS 

ttyxx : No such device or address 

A terminal which is turned on in the ttys file cannot be opened, probably 
because the requisite lines are either not configured into the system, the 
associated device was not attached during boot-time system 
configuration, or the special file in /dev does not exist. 
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FILES 

/etc/gettytab 
SEE ALSO 

gettytab(5), init(8), login(l), ioctl(2), tty(4), ttys(5); 
Using Your SysV Environment. 
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NAME 

glbd — Global Location Broker Daemon 
SYNOPSIS 

/etc/ncs/glbd [ -create { -first | -from hostjiame } ] 

DESCRIPTION 

The Global Location Broker Daemon (glbd), part of the Network Computing System 
(NCS), manages the Global Location Broker (GLB) database. The GLB database stores 
the locations of NCS-based server programs on a network or internet. 

The GLB can be replicated for greater availability of its database. Copies of the data- 
base can exist on several nodes, with the brokers maintaining consistency of the repli- 
cated database. (In an internet, at least one glbd must run in each network.) The 
drmadmin tool administers the replication of the GLB database. 

Access to the GLB database by clients is supported on both the DARPA IP and the 
Domain DDS network protocols. However, GLBs use only the DDS protocols to main- 
tain replication of the database. Thus, on an internet, all routing nodes must support 
DDS. 

A Local Location Broker Daemon (llbd) must be running on the local node when glbd 
is started. Typically, both brokers are started at boot time from the /etc/rc file. 

If glbd is to communicate via IP protocols, a TCP daemon (tcpd) must also be running 
on the local node, tcpd should be started before llbd. 

See Managing the NCS Location Broker for more information. 

Diagnostic output from glbd is written to the file node_data/system_logs/glb_log. 

OPTIONS 

-create Create a replica of the GLB. This option creates a GLB database in 
addition to starting a broker process. It must be used with either -first 
or -from. 

—first This option must be used with the —create option. Use it to create the 

first replica (i.e., the very first instance) of the GLB on your network or 
internet. 

—from hostjiame 

This option must be used with the -create option. Use it to create addi- 
tional replicas of the GLB. A replica of the GLB must exist at 
hostjiame. The database and replica list for the new replica are initial- 
ized from those at host name. The replica at host name adds an entry 
for the new replica to its replica list and propagates the entry to the other 
GLB replicas. 
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A hostjiame takes the form family’Jwst. The only currently supported 
family is dds; a host in this family is specified by its entry directory or 
its network address. For example, dds://jeeves and dds:#1234.abcd are 
acceptable host names. 

EXAMPLES 

Initialize and start the first replica of the GLB on this network or internet: 

$ /etc/server /etc/ncs/glbd -create -first & 

Start a subsequent replica of the GLB, initializing its database from host //jeeves: 

$ /etc/server /etc/ncs/glbd -create -from dds://jeeves & 

Restart an existing replica of the GLB: 

$ /etc/server /etc/ncs/glbd & 

Restart an existing replica of the GLB on remote host //bertie: 

$ crp -on //bertie /etc/server //bertie/etc/ncs/glbd & 

SEE ALSO 

drm_admin(lm), lb_admin(lm), llbd(lm), Managing the NCS Location Broker. 
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NAME 

hostns - convert host table files to resource record format 

SYNOPSIS 

hostns [ — f file ] [ — d domain ] [ -h host ] [ -n subnetid ] [ — s major. minor ] 

[ -u user ] 

DESCRIPTION 

The hostns command converts host address information obtained from an existing 
/etc/hosts format file (see hosts(4)) into Standard Resource Record Format for use by 
named(lM). It is intended to serve as an aid in bringing up the name server on an 
existing network. By default, hostns uses host address mapping information contained 
in the file /etc/hosts. 

OPTIONS 

— f file Specify an alternate host address mapping file, named file . 

— d domain Use domain as the domain name for the local zone. Normally if the 

current machine’s hostname contains any dots, the portion of the 
hostname after the first dot is taken to be the domain name for the 
local zone. If there are no dots in the hostname, the domain name 
defaults to .MY. DOMAIN. 

-h host Build files for a different host. Normally hostns assumes 

named(lM) will be run on the local machine and generates 
nameserver records. 

-n subnet jd Limit the conversion to the specific subnet. Normally, hostns con- 

verts all of the entries in the specified /etc/hosts file, subnet _id may 
be specified in hexadecimal or in the standard Internet “dotted 
address” format. The -n option may be specified, with a different 
subnet id, up to five times. 

-s major. minor Set the serial number in the Start of Authority (SOA) record to 
major. minor instead of 1.1. The serial number is used to detect 
updates in a running network. 

-u user Specify user as the responsible administrator. Normally, hostns 

assumes the user responsible for network administration is the user 
running the program. 
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FILES 

The following files are produced: 



named. boot 
named.ca 
named. local 
named. hosts 
named. rev 

SEE ALSO 

hosts(4), named(lM), nshost(lM); 
Configuring and Managing TCPIIP. 



boot file 

initial cache data 
localhost reverse pointer 
hosts file 

hosts file reverse pointers 
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NAME 

htable — convert NIC standard fonnat host tables 
SYNOPSIS 

/etc/htable [ -c connected-nets ] [ -I local-nets ] file 

DESCRIPTION 

The htable command is used to convert host files in the format specified in Internet 
RFC 8 10 to the format used by the network library routines. Three files are created as a 
result of running htable: hosts, networks, and gateways. The hosts file may be used 
by the gethostbyname(3) routines in mapping host names to addresses if the 
nameserver, named(lM), is not used. The networks file is used by the getnetent(3) 
routines in mapping network names to numbers. Tire gateways file may be used by the 
routing daemon in identifying “passive” Internet gateways; see routed(lM) for an 
explanation. 

If any of the files localhosts, loealnetworks, or local gateways are present in the 
current directory, the file’s contents are prepended to the output file. Of these, only the 
gateways file is interpreted. This feature allows sites to maintain local aliases and 
entries which are not nonnally present in the master database. Only one gateway to 
each network will be placed in the gateways file; a gateway listed in the localgateways 
file will override any in the input file. 

OPTIONS 

— c connected-nets 

If the gateways file is to be used, use this flag to specify a list of net- 
works to which the host is directly connected. The networks, separated 
by commas, may be given by name or in Internet-standard dot notation, 
for example, 

-c arpanet,I28.32,local-ether-net. 

htable only includes gateways that are directly connected to one of the 
specified networks, or that can be reached from another gateway on a 
connected net. 

—1 local-nets The argument is a comma-separated list of networks to be treated as 
“local”. List fonnat rules are the same as for — c. Information about 
hosts on local networks is taken only from the localhosts file. Entries 
for local hosts from the main database will be omitted. This allows the 
localhosts file to completely override any entries in the input file. 

htable is best used in conjunction with the gettable(lM) program which retrieves the 
NIC database from a host. If the name-domain system provided network name map- 
ping well as host name mapping, htable would no longer be needed. 
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SEE ALSO 

intro(3N, gettable(lM), named(lM); 
Configuring and Managing TCP! IP. 
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NAME 

id - print user and group IDs and names 

SYNOPSIS 

id 

DESCRIPTION 

id outputs the user and group IDs and the corresponding names of the invoking process. 
If the effective and real IDs are different, both are printed. 

SEE ALSO 

logname( I ) getuid(2) 
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NAME 

ifconfig - configure network interface parameters 
SYNOPSIS 

/etc/ifconfig interface [ address Jamily \ [ address [ dest_address ] ] [ parameters ] 
/etc/ifconfig interface [ protocol Jamily ) 

DESCRIPTION 

ifconfig is used to assign an address to a network interface and/or configure network 
interface parameters, ifconfig must be used at boot time to define the network address 
of each interface present on a machine. It may also be used at a later time to redefine an 
interface’s address or other operating parameters. The interface parameter is a string of 
the form name unit , for example, ethO. 

Since an interface may receive transmissions in differing protocols, each of which may 
require separate naming schemes, it is necessary to specify the address Jamily , which 
may change the interpretation of the remaining parameters. The only address family 
currently supported by Apollo is inet . 

For the DARPA-Intemet family, the address is either a host name present in the host 
name data base, hosts(4), or a DARPA Internet address expressed in the Internet stan- 
dard “dot notation”. 



PARAMETERS 

The following parameters may be set with i Icon fig: 

up Mark an interface “up”. This may be used to enable an interface 

after an “ifconfig down.” It happens automatically when setting the 
first address on an interface. If the interface was reset when previ- 
ously marked down, the hardware will be re-initialized. 

down Mark an interface “down”. When an interface is marked “down”, 

the system will not attempt to transmit messages through that inter- 
face. If possible, the interface will be reset to disable reception as 
well. This action does not automatically disable routes using the 
interface. 

trailers Request the use of a “trailer” link level encapsulation when sending 

(default). If a network interface supports trailers, the system will, 
when possible, encapsulate outgoing messages in a manner which 
minimizes the number of memory to memory copy operations per- 
formed by the receiver. On networks that support the Address Reso- 
lution Protocol (see arp(7); currently, only 10 MB ETHERNET*), 
this flag indicates that the system should request that other systems 
use trailers when sending to this host. Similarly, trailer encapsula- 
tions will be sent to other hosts that have made such requests. 
Currently used by Internet protocols only. 



9-54 



Commands 




IFCONFIG(IM) 



SysV 



IFCONFIG(IM) 



Disable the use of a “trailer” link level encapsulation. 

Enable the use of the Address Resolution Protocol in mapping 
between network level addresses and link level addresses (default). 
This is currently implemented for mapping between DARPA Internet 
addresses and 10MB ETHERNET addresses. 

— arp Disable the use of the Address Resolution Protocol. 

metric n Set the routing metric of the interface to n, default 0. The routing 

metric is used by the routing protocol (routed! 1M)). Higher metrics 
have the effect of making a route less favorable; metrics are counted 
as addition hops to the destination network or host. 

debug Enable driver dependent debugging code; usually, this turns on extra 

console error logging. 

—debug Disable driver dependent debugging code. 

netmask mask (Inet only) Specify how much of the address to reserve for subdivid- 
ing networks into sub-networks. The mask includes the network part 
of the local address and the subnet part, which is taken from the host 
field of the address. The mask can be specified as a single hexade- 
cimal number with a leading Ox, with a dot-notation Internet address, 
or with a pseudo-network name listed in the network table net- 
works^). The mask contains 1 ’s for the bit positions in the 32-bit 
address which are to be used for the network and subnet parts, and 
0’s for the host part. The mask should contain at least the standard 
network portion, and the subnet field should be contiguous with the 
network portion. 

dstaddr Specify the address of the correspondent on the other end of a point 

to point link. 

broadcast (Inet only) Specify the address to use to represent broadcasts to the 

network. The default broadcast address is the address with a host 
part of all l’s. 

ifeonfig displays the current configuration for a network interface when no optional 

parameters are supplied. If a protocol family is specified, ifeonfig will report only the 

details specific to that protocol family. 

Only the super-user may modify the configuration of a network interface. 



-trailers 

arp 
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DIAGNOSTICS 

Messages indicating the specified interface does not exit, the requested address is 
unknown, or the user is not privileged and tried to alter an interface’s configuration. 

NOTES 

ETHERNET is a registered trademark of the Xerox Corporation. 

SEE ALSO 

intro(7), netstat(l), rc(lM); 

Configuring and Managing TCP HP. 
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NAME 

import_pass\vd - create registry entries based on information in UNIX group and pass- 
word files 

SYNOPSIS 

/etc/import_passvvd [-i] [-a | -f] [ — c] [ -o org ] — s pathname [ — v ] 
DESCRIPTION 

import_passwd is a mechanism for creating Apollo registry entries that are consistent 
with foreign password and group file entries. You should use import_passwd to ensure 
consistency between Apollo and foreign protection mechanisms when you 

• Attach Apollo node(s) to an existing UNIX network 

e Attach UNIX node(s) to an Apollo network 

® Connect Apollo and UNIX networks 

If the foreign password and group file entries do not exist in the Apollo registry, 
importpasswd will create them. If there are duplicate entries, import_pass\vd will 
follow your directions on how to handle them. (Note that reserved names and reserved 
UNIX IDs cannot be reassigned.) 

The Process 

The Apollo registry must exist before you can use import_passvvd. If you are simply 
adding a few Apollo nodes to a foreign network, you can create a new, but empty, 
registry to meet this requirement. Once the registry exists, the registry server must be 
running, and you must be logged on as root. 

As iniport_pass\vd processes, it 

1. Examines the foreign group file and creates group entries in the registry. 

2. Examines the foreign passwd file and creates person, organization, and account 
entries in the registry. The organization assigned is specified as input to 
importpasswd. 

3. Reexamines the foreign group file and creates membership lists. 

Conflicts 

During this process, import_password may find conflicts in name strings (for example, 
in the foreign network, joe 102; in Apollo, joe 555) and in UNIX IDs (for example, in 
the foreign network, joe 102; in Apollo, ann 102). import passwd provides a number 
of options to help resolve these conflicts. 

The Favored Entry 

The -a (favor Apollo entry) or — f (favor foreign entry) options specify which entry 
should be favored. A favored entry is retained as is. You are prompted to modify non- 
favored entries. (Note, however, that in some cases you may be prompted to modify a 
favored entry. For example, if the non-favored entry is a reserved name, you will be 
prompted to modify the favored entry.) 
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Name Conflicts 

The — i option specifies that duplicate names are not in conflict but in fact, represent the 
same identity. Therefore, when duplicate names arise, no action is necessary. If you 
do not use the -i option, importpasswd resolves the name conflict by prompting for a 
name string for the non-favored entry. 

UNIX ID Conflicts 

The resolution of UNIX ID conflicts is also determined by the favored entry. If a 
conflict exits, you are prompted for a new UNIX ID for the non-favored entry. 

Other Registry Entries 

Except for names and UNIX IDs, all other information stored in the Apollo registry for 
an existing identity is retained. 

New registry entries created by import passwd are assigned the following values: 

For Person and Croup Entries: 
full name = " (empty) 

owner = Same as the owner of the organization specified with the — o option. If 
no organization is specified, then the owner of the organization named "none" 

alias/primary = Primary for first entry; alias for subsequent ones. 

projlist_ok = Yes. 

passwd = For groups only, taken from the group file. 

membership list = For new groups only, all persons listed in the group file, 
and all persons with accounts in the password file with that group. 

For Account Entries: 

abbreviation = Shortest possible abbreviation that does not conflict with pre- 
existing Apollo accounts. 

acount_valid =True. 

gecos = Same as UNIX password file. 

homedir = Same as UNIX password file. 

shell = Same as UNIX password file. 

passwd = Same as UNIX password file. Note that you must modify or reset 
imported passwords before user authentication is possible and for the account 
to be usable in a pre-SRIO registry. 

passwd_dtm = Date and time import_passwd was run. 

passwd_valid = True. 
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OPTIONS 
— i 

—a (default) 

-f 

-c 



Name strings are not in conflict, but represent the same identity. 

Favor Apollo entries for conflicts. 

Favor foreign entries for conflicts. 

Run in check mode: Process the command, showing all conflicts, but 
make no requests for resolution. 



— o org org is the name of an Apollo organization to be assigned to all imported 

entries. 



— s pathname pathname is the path to the directory containing the foreign password 
and group files to be imported. 

— v Run in verbose mode: Generate a verbose transcript of. importpasswd 

activity. 



SEE ALSO 

edrgy(lM), rgy_admin(lM), rgy_merge(lM), rgyd(lM) 
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NAME 

inetd - internet “super-server” 

SYNOPSIS 

/elc/inetd [ -d ] [ configuration file ] 

DESCRIPTION 

The inetd server should be run at boot time by /etc/rc. local. It then listens for connec- 
tions on certain internet sockets. When a connection is found on one of its sockets, it 
decides what service the socket corresponds to, and invokes a program to service the 
request. After the program is finished, it continues to listen on the socket (except in 
some cases which will be described below). Essentially, inetd allows running one dae- 
mon to invoke several others, reducing load on the system. 

Upon execution, inetd reads its configuration information from a configuration file 
which, by default, is /etc/inetd.conf. There must be an entry for each field of the 
configuration file, with entries for each field separated by a tab or a space. Comments 
are denoted by a “#” at the beginning of a line. The fields of the configuration file are 
as follows: 

service name 
socket type 

protocol 

wait/nowait 

user 

server program 

server program arguments 

The service name entry is the name of a valid service in the file /etc/services/. For 
“internal” services (discussed below), the service name must be the official name of 
the service (that is, the first entry in /etc/services). 

The socket type should be one of stream, dgrani, qraw, rdm, or seqpacket, depending 
on whether the socket is a stream, datagram, raw, reliably delivered message, or 
sequenced packet socket. 

The protocol must be a valid protocol as given in /etc/protocols. Examples might be 
tcp or udp. 

The wait! nowait entry is applicable to datagram sockets only (other sockets should have 
a nowait entry in this space). If a datagram server connects to its peer, freeing the 
socket so inetd can received further messages on the socket, it is said to be a “multi- 
threaded” server, and should use the nowait entry. For datagram servers which process 
all incoming datagrams on a socket and eventually time out, the server is said to be 
“single-threaded” and should use a wait entry, conisat (biff) and talk are both exam- 
ples of the latter type of datagram server, tftpd is an exception; it is a datagram server 
that establishes pseudo-connections. It must be listed as wait in order to avoid a race; 
the server reads the first packet, creates a new socket, and then forks and exits to allow 
inetd to check for new service requests to spawn new servers. 
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The user entry should contain the user name of the user as whom the server should run. 
This allows for servers to be given less permission than root. The server program entry 
should contain the pathname of the program which is to be executed by inetd when a 
request is found on its socket. If inetd provides this service internally, this entry should 
be internal. 

The arguments to the server program should be just as they normally are, starting with 
argv[0] , which is the name of the program. If the service is provided internally, the 
word internal should take the place of this entry. 

inetd provides several “trivial” services internally by use of routines within itself. 
These services are echo, discard, chargen (character generator), daytime (human read- 
able time), and time (machine readable time, in the form of the number of seconds 
since midnight, January 1, 1900). All of these services are tcp based. For details of 
these services, consult the appropriate RFC from the Network Information Center. 

inetd rereads its configuration file when it receives a hangup signal, SIGHUP. Services 
may be added, deleted or modified when the configuration file is reread. 

SEE ALSO 

comsat(lM), ftpd(lM), rexecd(lM), rlogind(lM), rshd(lM), telnetd(lM), tftpd(lM); 
Configuring and Managing TCP/IP. 
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NAME 

infocmp - compare or print out terminfo descriptions 

SYNOPSIS 

infocmp [-d] [-c] [-n] [-1] [-L] [-C] [-r] [-u] [-s d|i|l|c] [-v] [-V] [-«] 
[— \v width] [-A directory] [-B directory] [termname ...] 

DESCRIPTION 

infocmp compares a binary terminfo(4) entry with other terminfo entries, rewrites a 
terminfo(4) description to take advantage of the use= terminfo field, or prints a ter- 
minfo(4) description from the binary file (term(4)) in a variety of formats. In all cases, 
Boolean fields are printed first, followed by numeric fields, followed by string fields. 

infocmp compares the terininfo(4) description of the first terminal termname with each 
description given by the entries for the other terminal’s termnames . If a capability is 
defined for only one of the terminals, the value returned depends on the type of the 
capability: F for Boolean variables, —1 for integer variables, and NULL for string vari- 
ables. 

—I, — L, and — C produce a source listing for each terminal named. 

OPTIONS 

— d (Comparison option) Produce a list of each capability that is different. If you 

have two entries for the same or similar terminals, infocmp shows what is dif- 
ferent between the two entries. Use this when more than one person produces 
an entry for the same terminal and you want to see what is different between 
the two. 

— c (Comparison option) Produce a list of each capability that is common to the 

two entries. Capabilities that are not set are ignored. Use this as a quick check 
to see if the — u option is worth using. 

— n (comparison option) Produce a list of each capability that is in neither entry. If 

no termname is given, the environment variable TERM is used for both term- 
names. Use this as a quick check to see if anything was left out of the descrip- 
tion. 

—I (Source-listing option) Use the terminfo(4) names. 

— L (Source-listing option) Use the long C variable name listed in <term.h> 

— C (Source-listing option) Use the termcap names 

— r (Source-listing option) When using — C, put out all capabilities in termcap 

form. If no termnames are given, the environment variable TERM is used for 
the terminal name. The source produced by the — C option may be used 
directly as a termcap entry, but not all of the string parameters may be 
changed to the termcap format, infocmp converts most of the parameter 
information, and that which it doesn’t is plainly marked in the output and com- 
mented out. These should be edited by hand. All padding information for 
strings is collected and placed at the beginning of the string where termcap 
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expects it. Mandatory padding (padding information with a trailing ’/’) 
becomes optional. All termcap variables no longer supported by terminfo(4), 
but derivable from other terminfo(4) variables, are output. Not all ter- 
minfo(4) capabilities are translated; only those variables that were part of 
termcap are nonnally output. Specifying -r removes this restriction, allowing 
all capabilities to be output in termcap form. Note that because padding is 
collected to the beginning of the capability, not all capabilities are output, 
mandatory padding is not supported, and termcap strings are not as flexible, it 
is not always possible to convert a terniinf'o(4) string capability into an 
equivalent termcap fonnat. Not all of these strings can be converted. A sub- 
sequent conversion of the termcap file back into terminfo(4) fonnat will not 
necessarily reproduce the original terminfo(4) source. The follwoing are 
some common terminfo parameter sequences, their termcap equivalents, and 
some terminal types that commonly have such sequences. 



Terminfo 


Tenncap 


Representative Terminals 


%pl%c 


%. 


adm 


%pl%d 


%d 


hp, ANSI standard, vtlOO 


%pl%V%+%c 


%+x 


concept 


%i 


%i 


ANSI standard, vtlOO 


%pl%?%V%>%t%pl%’y’%+%; 


%>xy 


concept 


%p2 is printed before %pl 


%r 


hp 



— u (use= option) Produce a terminfo(4) source description of the first tenninal 

termname that is relative to the sum description given by the entries for the 
other terminals termnames . infocmp does this by analyzing the differences 
between the first termname and the other termnames and producing a descrip- 
tion with use= fields for the other tenninals. In this manner, you can to retrofit 
generic terminfo entries into a tenninal ’s description. Or, if two similar ter- 
minals exist, but were coded at different times or by different people so that 
each description is a full description, infocmp shows what can be done to 
change one description to be relative to the other. A capability is printed with 
an at-sign (@) if it no longer exists in the first termname , but one of the other 
termname entries contains a value for it. A capability’s value gets printed if 
the value in the first termname is not found in any of the other termname 
entries, or if the first of the other termname entries that has this capability 
gives a different value for the capability than that in the first termname. The 
order of the other termname entries is significant. Since the terminfo compiler 
tic(lM) does a left-to-right scan of the capabilities, specifying two use= 
entries that contain differing entries for the same capabilities produces dif- 
ferent results depending on the order that the entries are given in. infocmp 
flags any such inconsistencies between the other termname entries as they are 
found. Alternatively, specifying a capability after a use= entry that contains 
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that capability causes the second specification to be ignored. Using infocmp 
to recreate a description can be useful to make sure that everything was 
specified correctly in the original source description. Another error that does 
not cause incorrect compiled files, but slows down the compilation time, is 
specifying superfluous use= fields, infocmp flags any other termname use= 
fields that are not needed. 

-s Sort the fields within each type according to the argument below: 

d Leave fields in the order that they are stored in the terminfo database, 
i Sort by terminfo name. 

1 Sort by the long C variable name, 
c Sort by the termcap name. 

If no -s option is given, fields printed out are sorted alphabetically by the ter- 
minfo name within each type, except in the case of the -C or the -L options, 
which cause the sorting to be done by the termcap name or the long C vari- 
able name, respectively. 

— v Print tracing information on standard error as the program runs. 

— V' Print the version of the program in use on standard error and exit. 

-1 Print fields, one to a line. Otherwise, the fields are printed several to a line, to 

a maximum width of 60 characters. 

— w width 

Change the output to width characters. 

[—Adi rectory] [—^directory] 

(Changing databases) The location of the compiled tenninfo(4) database is 
taken from the environment variable TERMINFO. If the variable is not 
defined, or the terminal is not found in that location, the system terminfo(4) 
database, usually in /usr/lib/terminfo, is used. —A and — B may be used to 
override this location. —A sets TERMINFO for the first termname, and -B 
sets TERMINFO for the other termname s . Now you can compare descriptions 
for a terminal with the same name located in two different databases. This is 
useful for comparing descriptions for the same tenninal created by different 
people. Otherwise, the terminals would have to be named differently in the 
terminfiH. 4) database for a comparison to be made. 

NOTES 

The termcap database (from earlier releases of UNIX System V) may not be supplied in 

future releases. 

If no options are specified and zero or one termnames are specified, -I is assumed. If 

more than one termname is specified, — d is assumed. 
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FILES 

/ nsr/1 i b/ter mi n f'o/?/ * Compiled terminal description database 
DIAGNOSTICS 

malloc is out of space! 

There is not enough memory available to process all the terminal 
descriptions requested. Run infocmp several times, each time including 
a subset of the desired termnames. 

use= order dependency found: 

A value specified in one relative terminal specification is different from 
that in another relative terminal specification. 

'us e=term' did not add anything to the description. 

A relative terminal name did not contribute anything to the final descrip- 
tion. 

must have at least two terminal names for a comparison 
to be done. 

The -u, — d and — c options require at least two terminal names. 

SEE ALSO 

tic(lM), curses(3X), tenn(4), terminfo(4) captoinfo(lM) 
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NAME 

init — process control initialization 

SYNOPSIS 

/ete/init 

DESCRIPTION 

init is invoked as the last step in the boot procedure. It normally runs the automatic 
reboot sequence as described in reboot(8), and if this succeeds, begins multi-user 
operation. 

In multi-user operation, init ’s role is to create a process for each terminal port on which 
a user may log in. To begin such operations, it reads the file /etc/ttvs and executes a 
command for each terminal specified in the file. This command will usually be 
/ete/gettv. gettv opens and initializes the terminal line, reads the user’s name and 
invokes login to log in the user and execute the shell. 

Ultimately the shell will terminate because of an end-of-file either typed explicitly or 
generated as a result of hanging up. The main path of init, which has been waiting for 
such an event, wakes up and removes the appropriate entry from the file utnip, which 
records current users, and makes an entry in /usr/adm/wtmp, which maintains a history 
of logins and logouts. The wtmp entry is made only if a user logged in successfully on 
the line. Then the appropriate terminal is reopened and gettv is reinvoked. 

init catches the hangup signal (signal SIGHUP) and interprets it to mean that the file 
/etc/ttvs should be read again. The shell process on each line which used to be active in 
ttys but is no longer there is terminated; a new process is created for each added line; 
lines unchanged in the file are undisturbed. Thus it is possible to drop or add terminal 
lines without rebooting the system by changing the ttys file and sending a hangup sig- 
nal to the init process: use kill -HUP 1. 

init will terminate multi-user operations and resume single-user mode if sent a ter- 
minate (TERM) signal, that is, kill —TERM 1. If there tire processes outstanding which 
are deadlocked (due to hardware or software failure), init will not wait for them all to 
die (which might take forever), but will time out after 30 seconds and print a warning 
message. 

init will cease creating new gettv ’s and allow the system to slowly die away, if it is sent 
a terminal stop (TSTP) signal, i.e., kill -TSTP I. A later hangup will resume full 
multi-user operations, or a tenninate will initiate a single user shell. This hook is used 
by reboot(8) and halt(8). 

init’s role is so critical that if it dies, the system will reboot itself automatically. 
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DIAGNOSTICS 

/etc/getty genyargs failing, sleeping. 

A process being started to service a line is exiting quickly each time it is started. This 
is often caused by a ringing or noisy terminal line, init will sleep for 30 seconds, then 
continue trying to start the process. 

WARNING: Something is hung (won't die); ps axl advised 

A process is hung and could not be killed when the system was shutting down. This is 
usually caused by a process which is stuck in a device driver due to a persistent device 
error condition. 

FILES 

/dev/console 

/dev/ttv* 

/etc/utmp 

/usr/adm/wtmp 

/etc/ttys 

/etc/rc 

SEE ALSO 

login(l), kill(l), sh(l), ttys(5), getty(8), rc(8), reboot(8), halt(8), shutdown(8) 
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NAME 

install - install commands 

SYNOPSIS 

/etc/install [-c dira] [— f dirb] [-i] [-n dire ] [-m mode ] [-u user ] [-g group] [-o] 
[-s] file[ dirx . . .] 

DESCRIPTION 

install is most commonly used in “makefiles” [See make(l)] to install a file (updated 
target file) in a specific place within a file system. Each file is installed by copying it 
into the appropriate directory, thereby retaining the mode and owner of the original 
command. The program prints messages telling you exactly what files it is replacing or 
creating and where they are going. 

If no options or directories (dirx...) are given, install searches a set of default directories 
(/bin, /usr/bin, /etc, /lib, and /usr/lib, in that order) for a file with the same name as 
file. When the first occurrence is found, install issues a message saying that it is 
overwriting that file with file, and proceeds to do so. If the file is not found, the pro- 
gram states this and exits without further action. 

If one or more directories are specified after file, those directories are searched before 
the directories specified in the default list. 

OPTIONS 

-c dira Installs a new command (file) in the directory specified by dira , only if it 
is not found. If it is found, install issues a message saying the file 
already exists, and exits without overwriting it. You can use this option 
alone or with the — s option. 

— f dirb Forces file to be installed in the directory specified by dirb, whether or 

not one already exists. If the file being installed does not already exist, 
the mode and owner of the new file are set to 755 and bin, respectively. 
If the file already exists, the mode and owner are set to that of the 
already existing file. You can use this option alone or with the — o or — s 
options. 

— i Ignores the default directory list, searching only through the given direc- 

tories (dirx...). You can use this optionn alone or with any other options 
except — c and — f. 

-n dire If file is not found in any of the searched directories, it is put in the direc- 
tory specified in dire. The mode and owner of the new file are set to 755 
and bin, respectively. You can use this option alone or with any other 
options except -c and — f. 

— m mode The mode of the new file is set to mode. This option is available only to 

the super-user. 

-ii user The owner of the new file is set to user. This option is available only to 
the super-user. 
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-g group 
-o 



-s 



SEE ALSO 

make( 1 ). 



The group id of the new file is set to group. This option is available only 
to the super-user. 

If file is found, this option saves the “found” file by copying it to 
OLD file in the directory in which it was found. This option is useful 
when you install a frequently used file such as /bin/sh or /etc/getty, 
where the existing file cannot be removed. You can use this option alone 
or with any other options except -c. 

Suppresses printing of messages other than error messages. You can use 
this option alone or with any other options. 
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NAME 

invol - initialize disk volumes 
SYNOPSIS 

/etc/invol (from shell) 

e\ invol (from mnemonic debugger) 

DESCRIPTION 

invol initializes physical disk volumes, creates logical volumes, and maintains badspot 
lists. Once initialized, a volume can be mounted with the mount(lM) command, or can 
be used to bootstrap the operating system, providing it contains the necessary files, 
invol prompts for all required information. 

SUMMARY OF OPTIONS (Complete description follows.) 

0 Exit. 

1 [— fnbSuom] Initialize virgin physical volume. 

2 [-fnb5u] Add a logical volume. 

3 [— fnb5] Re-initialize an existing logical volume. 

4 Delete a logical volume. 

5 List logical volumes. 

6 List badspots on disk or volume. 

7 Create physical badspot list. 

8 Create or modify a Domain/OS paging file. 

9 Add to existing badspot list. 

10 Display/change sector interleave factor. 

1 1 Remove from existing badspot list. 

FLAGS SUMMARY 

—u Use defaults 

— f Don’t re-format disk 

— o Pre-SRIO format 

— n Make non-bootable volume 

-b Apply BSD UNIX ACLs 

-5 Apply SysV UNIX ACLs 

— m Make a multi-disk set 
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FULL DESCRIPTIONS OF OPERATIONS 

0 Exit 

1 [-fnbSuom] 

Initialize a virgin physical volume. 

Every new disk must be initialized before it can be used. When you initialize a 
new disk, all existing data on the disk are overwritten. Do not initialize a disk 
that contains any data you need to save. We initialize Winchester disks during 
the manufacturing process, before installing the system software. 

To initialize a new disk, follow this procedure: 

A. invol asks which option to perform. Type 7 to create or replace the bad- 
spot list. (See "Recording Badspot Information"). Type 9 if you want to 
add to the existing badspot list. Otherwise, type 1 to initialize a new 
physical volume. 

B. Specify the type of disk to initialize, invol prompts with: 

Select disk: [ w=Winch|s=Storage mod|f =Floppy|q=Quit ] 

[Ctrl# : ] [unit# ] 

Typing q (as always) will exit the program. 

invol (as well as salvol and fixvol) can deal with multiple controllers of 
the same type. The encoding of the controller# and unit# is as follows: 



w 


Winchester 


. . . Controller 


#0 . , 


. . Unit 


#0 


wl 


Winchester 


. . . Controller 


#0 . , 


. . Unit 


#1 


wl : 


Winchester 


. . . Controller 


#1 . , 


. . Unit 


#0 


wl : 2 


Winchester 


. . . Controller 


#1 . , 


. . Unit 


#2 



Thus a single character N following the s|w specifies a unit# on the first 
(O’th) controller. If this character is followed by a V character, it is 
taken to be a controller specifier which is then followed by an optional 
unit specifier. 

C. invol asks for the name of the physical volume. 

D. Choose one of the following verification options: 

1 - No verification 

2 - Write all blocks on the volume 

3 - Write and reread all blocks on the volume 
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If you choose no verification (option 1), invol does not read or write to 
the disk, except to create the volume structure. This option is the fastest, 
but means that the disk is not verified until it is mounted and read or 
written. 

If you choose the second option, invol attempts to write to each block on 
the disk. The third option, writing and rereading all blocks on the 
volume, is the safest but also the slowest. For example, to format a com- 
plete 33MB Winchester, option 1 requires about five minutes, option 2 
requires about fifteen minutes, and option 3 requires about 30 minutes. 

If a floppy disk is initialized with invol on a busy node, there is a small 
chance that a format operation will fail, but that the failure will not be 
reported to invol. For this reason, invol writes each block during floppy 
initialization, even for verification option 1. If a write fails after an 
apparently successful format, invol will print the message: 

format failed for daddr <disk_address> : <write status> 
— - retrying format 

and will reformat (and rewrite) the track in error. This happens whether 
or not the floppy has been previously initialized. 

E. Enter the average file size, when prompted: 

Expected average file size, in blocks 
(CR for default-5 blocks) : 

Press <RETURN> to accept the default value of 5 blocks. Supplying a 
relatively accurate value for the average file size can save space on the 
disk, because the volume table of contents (a system table) will be allo- 
cated more efficiently. 

F. invol requests the size (in blocks) and name of each logical volume to be 
created. After each entry, invol tells you how much space remains. 
After entering the size and name of all logical volumes, enter a blank 
line to terminate input. A physical volume can contain up to 10 logical 
volumes. For example: 

There are 1231 blocks available. 

volume 1: 1231, voll 

The logical volume size must be at least 30 blocks, and must be a multi- 
ple of the track size for the disk. If you specify a logical volume size 
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that is not a multiple of the track size, invol rounds it up to the next mul- 
tiple track size, and informs you. Note that the physical volume label 
occupies the first block on the volume. Thus, the size of the first logical 
volume is always one less than a multiple of the track size. 

Logical volume names are optional, and are used only when invol lists 
the logical volumes on the disk (option 5). You cannot change the name 
of a logical volume after creating it. 

G. invol requests badspot information by asking whether or not you wish to 
use the prerecorded badspot list shipped with the disk. Answer y[es]. 
To erase the existing list, answer no. If you want to initialize the physi- 
cal badspot list on a virgin disk, use option seven, not option one. Use 
option nine to add to an existing list. You must have a hardcopy of the 
badspots in order to enter them, invol has retained the badspot prompt in 
option one only for compatibility with existing shell files. After your 
affirmative response, invol displays the badspot list, indicating the physi- 
cal disk address, cylinder, head, sector, and byte offset range. 

If, in later operations, you wish to provide your own badspot informa- 
tion, these can be entered in one of several formats: 

If the disk is a floppy: only HEX disk (block) addresses may be entered. 

If a multi-disk set was assigned, only HEX physical disk (block) 
addresses can be entered (as reported by salvol, Isyserr or disk_err). 
These disk addresses are relative to the entire set. For example: for a 
multi-disk set, daddr 0 is on the 1st drive, 1 is on the 2nd one, etc. 

Otherwise, the user has the option of entering the following: 

HEX physical disk (block) addresses 

DECIMAL cylinder-head byte_offsetl [byte_offset2 ...] 

up to 8 byte offsets can be 
specified per-line (for the 
same cylinder/head) 

HEX $cylinder-head sector 1 [sector2 ...] 

up to 8 sectors can be specified 
specified per-line (for the 
same cylinder/head) 



Commands 



9-73 




INVOL(IM) 



INYOL(IM) 



Domain/OS SysV 



Input continues until the user enters a blank line at which time he is 
given an opportunity to start over again (ignoring everything entered 
thus far). 

If the disk contains logical volume badspots lists (see earlier) the badspot 
changes are propagated to these lists as well. 

H. invol initializes the disk. As formatting proceeds, invol displays mile- 
stone messages to report its progress. It also displays a message for each 
volume it initializes, and another when it completes. 

I. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

2 [-fnbSu] 

Using option 2, you can partially initialize a volume, that is, add logical 

volumes to a physical volume, while preserving the existing logical volumes. 

Follow this procedure: 

A. invol asks which option to perform. Type 2 to partially initialize a disk. 

B. Specify the type of disk to initialize. (See option 1 step B.) 

C. invol prints a list of the logical volumes and vacancies on the disk. If 
the disk has more than one vacancy, invol asks where to place the new 
logical volume by requesting a vacancy number. Indicate the vacancy 
that you want invol to use by entering its number. If there are logical 
volumes following the vacancy that you choose, invol prints a warning 
message and then automatically increments the volume numbers of those 
succeeding volumes by one. 

D. Choose a verification option for the logical volume being initialized. 
(See option l step D.) 

E. Enter the expected average file size, in blocks. (See option 1 step E.) 
Press <RETURN> for the default value, 5 blocks. 

F. Enter the name and size of each logical volume to be formatted. (See 
option 1 step F.) After each specification, invol informs you of how 
much space is available. Terminate input with a blank line. A physical 
volume may have up to ten logical volumes. 

G. Enter badspot information. (See option 1 step G.) Terminate badspot 
entry with a blank line. 

H. Enter the name of the physical volume. (See option 1 step C.) 

I. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

3 [-fnb5] 

You can reinitialize a logical volume, retaining its size and name, with option 3. 
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AIL existing data in the volume will be lost. This option is useful for reinitializ- 
ing floppy disks, where one logical volume typically occupies the entire physi- 
cal volume. 

To reinitialize a single logical volume, use the following procedure: 

A. invol asks which option to perform. Type 3 to reinitialize a logical 
volume. 

B. Specify the type of disk to initialize. (See option 1 step B.) 

C. invol prompts for the # (I..N) of the logical volume to be re-initialized. 

D. Choose a verification option: no verification, write all blocks, or write 
and reread all blocks. (See option 1 step D.) 

E. Enter the expected average file size, in blocks. (See option 1 step E.) 
Press <RETURN> for the default value, 5 blocks. 

F. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

4 Delete a logical volume. 

To delete a logical volume, use the following procedure: 

A. invol asks which option to perfonn. Type 4 to delete a logical volume. 

B. Specify the type of disk from which the volume will be deleted. (See 
option 1 step B.) 

C. Enter the number of the logical volume to delete. You can determine the 
logical volume numbers present on a disk with option 5. 

D. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

Note: invol renumbers the logical volumes following the deleted 
volume. 

5 Listing logical volumes 

Logical volumes on the disk are displayed. Pre-SRIO fonnat logical volumes 
are flagged as such in the output. To list the logical volumes on a disk, use the 
following procedure: 

A. invol asks which option to perform. Type 5 to list the logical volumes 
on a disk. 

B. Specify the type of disk. (See option 1 step B.) invol lists the volumes 
on that disk. 
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C. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

List badspots on disk or volume. 

To list the badspots in one or more logical volumes, or for the physical volume, 

use the following procedure: 

A. invol asks which option to perform. Type 6 to list badspots. 

B. Specify the type of disk. (See option 1 step B.) 

C. Specify the badspots to be listed, by entering one of the following: 
m[fg] For ESDI drives only: 

The contents of the manufacturer supplied badspot list is 
displayed. Physical disk (block) addresses are displayed in HEX 
along with the corresponding HEX (as opposed to decimal pre- 
SR10) cylinder/head/sector addresses and DECIMAL byte 
offset range. 

Note: Users should generally have no reason to use this option as this 
list is usually copied to the physical badspot list/cylinder as soon 
as a disk is received. On some disks, moreover, this 
manufacturer’s list is destroyed as soon as the disk is invol’d 
(option 1). 

p[hys] For Winchester and Storage-Module drives only: 

Displays the contents of the physical badspot list. Physical disk 
(block) addresses are displayed IN HEX along with the 
corresponding HEX (as opposed to decimal pre-SRIO) 
cylinder/head/sector addresses and DECIMAL byte offset range. 

If the specified disk is the primary drive for a multi-disk set, the 
physical disk addresses are relative to the entire set and a disk 
identifier is displayed along with the cylinder/head/sector. This 
disk identifier consists of a controller number and drive/unit 
number. For example: 

phys cylinder head sector byte offset C_num Drv_Unit 
daddr range 



123a9f 12d e 5 7123-8034 0 2 

If the specified disk is a non-primary member of a multi-disk set 
(i.e., the s option was used to examine a single drive only, see the 
— m option below), then the physical disk addresses that are 
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displayed are relative to that drive and do not correspond in any 
way to logical/physical disk addresses for the disk-set as a whole 
(i.e., as displayed by lyserr or disk_err). 

n Badspots that lie within the specified logical volume are 
displayed: n can be any integer from 1 through 10. Both logical 
and physical disk addresses are displayed in HEX. 

The specified disk must hold a valid pv and lv labels. The pri- 
mary member of a multi-disk set must have been specified. 

Note: cylinder/head/sector values are not displayed. 

For a multi-disk set, the primary drive of the set must have been 
specified earlier. Physical disk addresses are relative to the entire 
set. 

a[U] Badspots for all logical volumes on the disk (or multi-disk set) 
are displayed: this format is identical with that of 1..10 discussed 
above. 

D. invol asks if you have any more requests. Type v[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

7 Create physical badspot list. 

Note: This option acts upon a single disk drive, regardless of whether it is a 
member of a multi-disk set or not. Generally speaking, this operation is 
run on a disk as it arrives from the factory and should not need to be per- 
formed again. 

Using option 7, you can create or replace the badspot list on the disk. 
(Use option 9 to add badspots to an existing badspot list.) 

A. invol asks which option to perform. Type 7 to enter the disk’s badspot 
list. 

B. Enter the location of the badspots, one per line. (See option 1 step G for 
the proper format.) Tenninate badspot information with a blank line. 

C. After you have typed in the list, invol asks you to check for errors. If 
you made any errors in the list, you must retype the entire list by return- 
ing to step A and beginning again. 

D. invol asks if you have any more requests. Type v[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

8 Create or modify a Domain/OS paging file on an existing logical volume. 

You can create an operating system file or modify the size of an existing one. 
The Domain/OS paging file is required if you intend to run the operating system 
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off of this logical volume. 

To create or modify a Domain/OS paging file, perform the following steps: 

A. invol asks which option to perform. Type 8. 

B. Specify disk type. (See option 1 step B.) 

C. Specify logical volume number. The logical volumes present on a disk 
may be listed using option 5. 

D. If a Domain/OS paging file already exists on this volume, inv ol displays 
the file’s current size and asks if you want to change it. If you reply 
v[es], invol proceeds to step E. If you reply n[o], invol skips to step F. 

E. invol prompts you to enter the number of pages you want in the OS pag- 
ing file. Press <RETURN> to use the default, 352 pages. Type 0 (zero) 
to delete an existing paging file, or specify any number of pages between 
1 and 288. If the size you enter is larger than the current Domain/OS 
paging file, invol displays milestones as it initializes new disk records. 

F. invol asks if you have any more requests. Type y[es] to return to step A, 
or type n[o] to return to the calling program (shell or Mnemonic 
Debugger). 

9 Add to existing badspot list. 

Using option 9, you can add to the disk’s existing badspot list. Run salvol when 
this operation is done. 

A. invol asks which option to perfonn. Type 9 to add to the disk’s badspot 
list. 

B. Enter the location of the badspots, one per line. (See option 1 step G for 
the proper foimat.) Tenninate badspot information with a blank line. 

C. After you have typed in the list, invol asks you to check for errors. If 
you made any errors in the list, you must retype the entire list by return- 
ing to step A and beginning again. 

D. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

10 Display/change sector interleave factor for a logical volume. 

Using option 10, you can set or display the sector interleave factor for a volume. 
The correct interleave factor is set when a logical volume is created. However, 
as performance improvements are made, it may become necessary to change it 
to achieve optimal block read/write rates. Operation 10 displays the current 
value and the optimal value which we recommend. 
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A. invol asks which option to perform. Type 10 to set or display the sector 
interleave factor. 

B. Specify disk type. (See option 1 step B.) 

C. invol displays a list of logical volumes for that physical volume. Specify 
the appropriate logical volume number, invol then displays the current 
sector interleave factor and the value which we recommend. 

D. invol prompts for the new interleave factor. If you do not wish to change 
the interleave factor, enter a carriage return. 

E. invol asks if you have any more requests. Type y[es] to return to step A, 
or type n[o] to return to the calling program (shell or Mnemonic 
Debugger). 

1 1 Remove badspots from existing badspot list. 

Using option 11, you can subtract from the disk’s existing badspot list. Run sal- 

vol when this operation is done. 

A. invol asks which option to perform. Type 1 1 to remove from the disk’s 
badspot list. 

B. Enter the location of the badspots, one per line. (See option 1 step G for 
the proper format.) Tenninate badspot information with a blank line. 

C. After you have typed in the list, invol asks you to check for errors. If 
you made any errors in the list, you must retype the entire list by return- 
ing to step A and beginning again. 

D. invol asks if you have any more requests. Type y[es] to return to step A, 
or n[o] to return to the calling program (shell or Mnemonic Debugger). 

FULL DESCRIPTION OF FLAGS 

— u Use defaults. You are prompted for as little information as possible. A physi- 
cal volume is automatically chosen as follows (for option 1): 

pv_wxy_year . month . day w: disk type (or s or f) 

: controller # 

y : unit # 

year . month . day : today's date 

A single logical volume spanning the entire physical volume (for options 1 and 
2) is constructed and chosen as follows: 

lv_year . month . day 
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A non-bootable volume is constmcted. By default, invol places the following 
objects on each logical volume that it constructs: 



lost+found. list 

* sysboot 

II 
/ 

* Is ys 

* /sys/node_data 

* /sys/node_data/system_logs 

If the -n flag is specified, the objects marked * are not placed on the disk. 
Although the disk can be mounted, it can not be used as a boot volume (unless 
it is re-invol’d). 

Do not physically reformat the disk. By default, invol performs the very 
time-consuming task of re-formatting every track on the disk. This flag 
bypasses that operation and causes invol to execute very quickly, especially so 
if it is coupled with Verification option 1. Normally, it is only necessary to 
reformat disks as they arrive from the factory or after you have reason to 
suspect that the physical formatting is damaged or otherwise corrupted. 

BSD style initial acls (for inheritance) are placed onto /sys and /sys/node_data 
when they are constructed: 

owner/org: ids from creating process 

group: id taken from parent directory 

(set to wheel for /sys and 
/ sys/node_data) 

<all> rights: specified (usually from umask) 

at create time 



lost+found file for Salvol's later 
use space is reserved for sysboot 
(although the cpboot command must 
be issued to actually install it 
there) 

local network root 

entry directory for volume 



SysV style initial acls (for inheritance) are placed onto / sys and 
/sys/node_data when they are constmcted: 

owner/group/org : ids from creating process 

rights specified (usually 
from umask) at create time 
world rights : " " " 

By default, Aegis inclusive initial acls are applied. 
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owner /group/org : ids from creating process 

rights set to [ignore] 
world rights: pwrx (wide-open) 

Use only with option 1. A pre-SRIO format disk is configured which can be 
mounted under a pre-SRIO version of the operating system. By default, a 
SR 10 format disk is created which cannot be mounted by a pre-SRIO node. 
The presence or absence of this flag controls whether subsequent logical 
volumes on this volume will have SR 10 format (the new file system, acls and 
directories) or the pre-SRIO one. 

Use after option 1 to group multiple physical disks together into a multi-disk 
set which thereafter will appear to be a single large disk (to salvol, mho!, 
dmtvol, etc.). 

If you answer the invol prompt with 1 — m to indicate that a multi-disk group is 
to be configured, you will get the following prompts: 

A. Select disk: [w=Winch|s=Storage mod|f=Floppy|q=Quit| [Ctrl#:] [unit#] 

invol prompts for the identity of the first of the disks. Assume that the 
user responds with \v0: 1 . Subsequently, this drive becomes the pri- 
mary disk of the set: it is the one which must be specified in order to 
mount or otherwise use the set. 

B. How many disks will you be grouping together? 

invol prompts for the number of disks to be collected into the set. 
Currently, the only legal responses are 1, 2 or 4. 

C. Enter the striping option. 

invol prompts for the algorithm to be used in spreading disk blocks 
across the multiple drives in the set: 

1 . Sector striping (subsequent sectors to different drives) 

This is usually the choice for DN10000 workstations. Subse- 
quent disk blocks are sent to alternate disk drives (e.g., disk 
block N is sent to a different drive from N-l and N+l); this is 
the "classical" definition of disk striping. 

2. Cylinder striping (subsequent cylinders to different drives) 

This is usually the choice for 68000-based workstations. The 
cylinders from the various disks are "stacked" on top of one 
another so that it appears that each cylinder has N (2 or 4) times 
as many platters. Subsequent disk blocks will reside on the 
same drive unless a cylinder boundary is crossed, in which case 
we drop to the next disk in the set or wrap to the next cylinder 
of the first (primary) disk drive. 
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D. Physical volume name: 

invol prompts for the name of the physical volume. 

Enter remaining members of disk group: 

Select disk: [w=Winch|s=Storage mod|f=Floppy|q=Quit][ctrl#:][unit#] 
Select disk: [w=Winch|s=Storage mod|f=Floppy|q=Quit] [Ctrl#:] [unit#] 
invol prompts for the identity of the additional disk drives in the set. 
Obviously, no two drives in the set can have identical controller and 
unit numbers. 

This — m flag for option 1 is allowable only if: 

A. invol is running under an SR 10 operating system. 

B. An SR 10 format disk is being configured. 

C. A Winchester drive is selected. Only Winchester drives may be 
configured as a multi-disk set in this fashion. All drives in the set 
must have identical geometries: specifically, the blocks_per_track, 
sects_per_track, tracks_per_cylinder, blocks_per_volume, 
blocks_per_physical_volume, physical_badspot_daddr and 
physical_diagnostic_daddr attributes must all agree. 

Note: Be aware that what is constructed is a single physical volume 
spanning multiple disk drives. Any logical volumes later built 
span all disk drives of the set. There is no way to cause a sin- 
gle file or logical volume to be limited to a single drive of the 
set. Contained within the pv label of the primary drive (as 
well as the others) is information identifying the other drives 
of the set as well as consistency data to detect the re-invol or 
replacement of any of the drives. 

Relation of invol options to multi-disk sets: 

The following invol options, when given the specifier of the primary drive of a 
set, will operate upon the entire set: 

2 add a logical volume to an existing physical volume. 

3 re-initialize an existing logical volume. 

4 delete a logical volume. 

5 list logical volumes. 

6 list badspots: unless [ sj is specified - <see below>. 

8 create Domain/OS paging file. 

9 add to badspot list: unless [ s] is specified - <see below>. 

10 changing interleave factor for a logical volume. 

1 1 delete from badspot list: unless [ s] is specified - <see below>. 

Several invol options will only operate upon a single disk drive - regardless of 
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whether it is a member of a multi-disk group: 

I as detailed above, the specified drive is re-initialized regardless of 
its current status as a member of some multi-disk set ... optionally, 
a new multi-disk set can be established. 

7 a physical badspot list on the specified drive is constructed 
(this option needs to be run when the drive arrives 
from the factory, and not again). 

Several invol options allow the user to specify that only a single drive 

is to be assigned/processed, even if that drive is a member of a multi-disk set: 

6 list badspots : only the physical (or manufacturer’s) badspot list can 
be shown in this case. 

9 add to badspot list : badspots may be entered as either physical disk 
addresses or as cylinder-head-sector triplets - both relative to that 
single drive as if it was not a member of a multi-disk set. 

I I delete from badspot list : see the above discussion for 9. 

For these cases, the "assign" prompt given to the user specifies that the user is 
allowed to follow the disk specifier with a " s" (<space> , "s") to indicate that 
even though the disk is a member of a multi-disk set, only the specified (sin- 
gle) disk is to be accessed. For example: 

Select disk: [ w=Winch|s=Storage mod|f =Floppy|q=Quit ] 

[Ctrl#:] [unit#] wO:ls 
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NAME 

killall - kill all active processes 

SYNOPSIS 

/etc/killall [ signal ] 

DESCRIPTION 

killall uses /etc/shutdown to kill all active processes not directly related to the shut- 
down procedure. 

killall terminates all processes with open files so that the mounted file systems are freed 
and can be unmounted. 

killall sends signal (see killfl]) to all processes that are not part of the above group of 
exclusions. If you do not specify signal, the default signal - 9 - is used. 

FILES 

/etc/shutdown 
SEE ALSO 

shutdown(lM), kill(l), ps(l) 
signal(2) 

NOTE 

Only a super-user can ran killall. 
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NAME 

Ib_admin — Location Broker Administrative Tool 

SYNOPSIS 

/etc/ncs/lb_admin 

DESCRIPTION 

The lb_admin tool monitors and administers Location Broker registrations. It presents 
both a Domain/Dialogue (tm) based user interface and a terminal-oriented interface. 
For information about the Domain/Dialogue interface, use the HELP key while running 
the tool. Information about individual commands for the terminal -oriented interface is 
available through the help command. 

COMMANDS 
help 

quit 

lookup 

register 

set_broker 

usebroker 

un register 

NOTES 

The Domain/Dialogue menus display object, type, and interface UUIDs when that 
operand is chosen via the switch at the top of the menu. The UUIDs displayed are those 
belonging to the entries of the broker selected in the top line when the update operation 
is performed. When an item is selected from a menu, the UUID appears in the Entry 
Information form and the next menu in the object, type, interface trio is displayed. 

The asterisk (*) acts as a wildcard for the lookup and unregister operations. 



List available commands or get information about a specific command. 
Exit the lb_admin session. 

List matching Location Broker entries. 

Add an entry to the Location Broker database. 

Select the specific Location Broker to use. 

Direct operations to a Local Location Broker or to a Global Location 
Broker. 

Delete an entry from the Location Broker database. 



SEE ALSO 

drm_admin(lM), glbd(lm), llbd(lm) 
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NAME 

lenet - display internet routing information 

SYNOPSIS 

/etc/lenet [ options ] 

DESCRIPTION 

lenet displays the list of known networks, their distance from the current node, the 
router used as the first hop from that network, and other information. 

The distance (hops) from remote networks is measured in intervening routers. The dis- 
tances are all for one-way traffic; if a network is three hops away from yours, your 
requests pass through three routers to get to that network. The responses also pass 
through three routers on the way back. 

The -conn option shows you the full internet topology; that is, the list of networks and 
how the routers connect them together. 

OPTIONS 

—local (default) 

Display the "First Hop" and "Hops" information for each network in the 
internet. The first hop is the node ID of a router on your network. It is 
the first router used in sending packets from your network to the target 
network. Other routers are also used if the target network is more than 
one hop away from your own. 

Display information showing how up to date the routing table is (the 
"Age" and "Expiration" columns) in addition to the "First hop" and 
"Hops" infonnation shown by the —local option, -full also lists inacces- 
sible networks. 

Show which routers are connected to each network, and which other net- 
works those routers touch. This option displays the "Touching" informa- 
tion. 

Display the type of hardware used for each of the networks (ring or IIC). 

The —conn and — h\v options may take several seconds to execute if you 
have a large internet. 

— n node -spec Print another node’s view of the internet. The outputs produced by 
—local and —full vary from node to node; -n affects these outputs. The 
-n option does not affect the output produced by the -conn or — h\v 
options, since the hardware and connectivity do not depend on a node’s 
position in the internet. 



-full 



-conn 



— hw 
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-c The -c option suppresses the title over each output column. It also fills 

every line of the "Network" column produced by the —conn option, and 
every line of the "Hardware" column produced by the — hw option. These 
format changes make it easier to use Icnet’s output as another program’s 
input. 

EXAMPLES 

In this example, the node is directly connected to network COFFEE. Networks 5A1AD 
and EDIFICE were connected in the past, but are not now accessible (perhaps because 
the routers are down). 

The expiration date and time for the "local" network are meaningless. 

$ /etc/lcnet -full 



Network 


First 

Hop 


Hops 


Age 


Expiration 


date/time 


B020 


4B6F 


1 


NEW 


1987/06/16 


14:33:21 


B00B00 


4B6F 


2 


NEW 


1987/06/16 


14 : 33:21 


5A1AD 


4B6F 


gone 


NEW 


1987/06/16 


14:33:21 


COFFEE 


0 


local 


NEW 


1987/06/09 


10:27 : 46 


EDIFICE 


4B6F 


gone 


NEW 


1987/06/16 


14:33:21 


DODO 


BAD1 


1 


NEW 


1987/06/16 


14:33:39 



The "Touching" infonnation describes your internet completely. This example includes 
several kinds of information: 

- Network DEFACED has one router, node 2A3B. 

That router connects DEFACED to EFFACED. 

- Network FACEOFF contains two routers, 31DC and 1371. 

Those routers connect FACEOFF to COCOA and COFFEE, 
respectively . 
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$ /etc/lcnet -conn 





Touching 


Touching 


Network 


Router 


Network 


FOOD 


5C0B 


DECAF 




3 6CF 


COFFEE 


5A1AD 


459B 


COFFEE 




45BE 


EDIFICE 


B002E 


3F0A 


COFFEE 


COCOA 


BAD1 


B00B1E 




5 6B0 


EFFACED 




31DC 


FACE OFF 


DECAF 


5C0B 


FOOD 


B00B1E 


BAD1 


COCOA 


COFFEE 


3 6CF 


FOOD 




459B 


5A1AD 




3F0A 


B002E 




1371 


FACE OFF 


DEFACED 


2A3B 


EFFACED 


EDIFICE 


4 5BE 


5A1AD 


EFFACED 


56B0 


COCOA 




2A3B 


DEFACED 


FACE OFF 


31DC 


COCOA 




1371 


COFFEE 



$ /etc/lcnet -conn ■ 


-c 




FOOD 


5C0B 


DECAF 


FOOD 


3 6CF 


COFFEE 


5A1AD 


4 5 9B 


COFFEE 


5A1AD 


4 5BE 


EDIFICE 


B002E 


3F0A 


COFFEE 


COCOA 


BAD1 


B00B1E 


COCOA 


56B0 


EFFACED 


COCOA 


31DC 


FACE OFF 


DECAF 


5C0B 


FOOD 


B00B1E 


BAD1 


COCOA 


COFFEE 


3 6CF 


FOOD 


COFFEE 


459B 


5A1AD 


COFFEE 


3F0A 


B002E 


COFFEE 


1371 


FACE OFF 


DEFACED 


2A3B 


EFFACED 


EDIFICE 


45BE 


5A1AD 


EFFACED 


5 6B0 


COCOA 
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EFFACED 

FACEOFF 

FACEOFF 



2A3B 

31DC 

1371 



DEFACED 

COCOA 

COFFEE 
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NAME 

Icnode - list nodes connected to the network 

SYNOPSIS 

/etc/lcnode [ options ] 

DESCRIPTION 

Icnode lists the nodes currently connected to the network. The list contains the ID of 
every node connected, the time at which the node was started, the current time, and the 
name of each node’s entry directory. 



This command reports only the nodes that respond within a preset time limit. If a node 
is connected, but temporarily unable to respond within the specified time, it does not 
appear in the produced list. 



OPTIONS 

Request information about your node only. This option displays 
the node ID. 

Request brief output. Icnode lists only the entry directory name 
for each connected node. Note that the entry directory of a disk- 
less node is the entry directory of its paging partner. 

When used with —brief, display the node ID in addition to the 
entry directory. 

Request node count only. Icnode lists only the number of nodes 
responding to its query. 

Set a limit on the number of nodes you want to see, even if more 
could respond. 

—from node_spec Starts the node list at some node other than your own. This is 
especially useful in an internet environment, for looking at net- 
works other than your own. See help node_spec for details 
about node specification syntax. 

—name When you specify the —brief option, Icnode normally prints the 

entry directory for each node. If you specify —name with —brief, 
Icnode prints the node name cataloged with the naming server. 
Only diskless nodes are printed differently. A diskless node’s 
entry directory is its partner’s node name; a diskless node’s node 
name is uniquely its own. 



-m[e] 

— b[rief] 

— id 

-c[ount] 
-ma\[nodes] n 



Unless the —from option specifies your own node, the list 
includes only an unbroken sequence of nodes running Aegis 
SR9.0 or later. The rest of the node list is lost, starting with the 
first node running a pre-SR9.0 Aegis. 
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EXAMPLES 

1. $ /etc/lcnode 

The node ID of this node is 21 . 3 other nodes responded. 

id Boot time Current time Entry Directory 

21 1987/06/09 9:21:44 1987/06/09 16:06:22 //dollar 

17 1987/06/09 13:52:02 1987/06/09 16:06:13 _ //quarter 

27 1987/06/09 12:53:28 1987/06/09 16:06:07 " //nickel 

11 1987/06/09 12:03:39 1987/06/09 16:06:15 ** DISKLESS ** 

//diskless_$ll partner node: 17 

2. $ /etc/lcnode -me 

The node id of this node is 21. 

3. $ /etc/lcnode -b 

/ / dollar 
//quarter 
/ / nickel 
/ / quarter 

(//quarter appears once as the host for a diskless node and 
once for the node with the disk.) 

4. $ /etc/lcnode -b -name 

//dollar 

//quarter 

//nickel 

//diskless_$000011 

(-name shows you the name under which diskless node 1 1 
is cataloged) 

5. $ /etc/lcnode — c 

466 other nodes responded. 

6. $ /etc/lcnode -c -b 

466 
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7. $ /etc/lcnode -c -m 

The node id of this node is 116A. 

4 66 other nodes responded. 

8. $ /etc/lcnode -b -id 

21 //dollar 
17 //quarter 
27 //nickel 
11 //quarter 

9. $ /etc/lcnode -from OF AD.3924 -max 2 

Starting from node 3924. 

1 other node responded, 

but more might have responded with a high -max value. 

Node id Boot time Current time Entry Directory 

3924 1985/02/14 17:20:45 1985/02/14 19:07:04 //laurel 

34Bf 1985/02/14 18:46:52 1985/02/14 19:08:09 //hardy 
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NAME 

link, unlink - link and unlink files and directories 

SYNOPSIS 

/etc/link filel file2 
/etc/unlink file 

DESCRIPTION 

link creates a filename that points to another file, unlink removes linked files and 
directories; however, it is strongly recommended that you use rm(l) and rmdir(l) 
instead of unlink. 

The difference between link/unlink and ln(l) is that link/unlink link and unlink 
without error checking. This is because they directly invoke the link(2) and unlink(2) 
system calls. 

SEE ALSO 

rm(l), link(2), unlink(2) 

WARNING 

Only super-user can run these commands. 
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NAME 

llbd - Local Location Broker Daemon 

SYNOPSIS 

/etc/ncs/llbd 

DESCRIPTION 

The Local Location Broker Daemon (llbd) is part of the Network Computing System 
(NCS). It manages the Local Location Broker (LLB) database, which stores informa- 
tion about NCS-based server programs running on the local node. 

A host must run llbd if it is to support the Location Broker forwarding function or to 
allow remote access (e.g., by the lb_admin tool) to the LLB database. In general, any 
node that runs an NCS-based server program should run an llbd. Additionally, any net- 
work supporting NCS activity should have at least one node running the Global Loca- 
tion Broker Daemon (glbd). Typically, both daemons are started at boot time from the 
/etc/rc file. 

To start llbd on a node that is already running, type the following at a shell prompt: 

$ /etc/server /etc/ncs/llbd & 

To have llbd start every time a node boots, use touch or erf to create the file 
/etc/ daemons/ll bd . 

If llbd is to support remote access from hosts in the IP address family, a TCP daemon 
(tepd) must be running on the local node; tepd should be started before llbd. 
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NAME 

loginsh - start a log-in shell 

SYNOPSIS 

/sys/dm/login_sh 

DESCRIPTION 

The loginsh command is included in your Display Manager (DM) log-in start-up 
script to create a shell when you log in. 

When you log in to the DM, it: 

® Checks the /elc/passwd file (the registry) to determine your HOME directory and 
preferred SHELL. 

® Looks for your system type by reading the .systvpe file in your home directory. If 
you don’t have a .systvpe file, Iogin_sh reads the file /etc/environ and uses the sys- 
type listed in that file. Valid systypes are bsd4.3, sys 5.3, and aegis. 

o Prints the “message of the day’’ from the /etc/motd file if your login shell is esh. 
(The other shells get the message of the day by running /etc/prolile.) 

© Executes the specified shell as a log-in shell. If the Bourne or the Korn shells 
(/bin/sh or /bin/ksh) are run as log-in shells, they execute /etc/prolile and '/.profile. 
The C shell (/bin/csh) executes the '/.login file. 

If /etc/passwd doesn’t specify a shell, login_sh runs sh. 

NOTES 

loginsh is intended to replace the start_sh and start_csh commands. To avoid execut- 
ing the log-in scripts /etc/profile, .profile, or .login more than once, you should create 
only one log-in shell. 

The /etc/environ file establishes the default environment and default systype for the 
node. The /etc/environ file can contain two lines, specifying the ENVIRONMENT 
value, and the SYSTYPE values. Valid ENVIRONMENT values are: aegis, bsd, or 
sysv. Valid SYSTYPE values are: aegis, bsd4.3, or sys5.3. If the ENVIRONMENT is 
set to aegis, you can add a line specifying either bsd4.3 or sys5.3. For example, if the 
file contains the following lines, login_sh executes an Aegis shell (unless another shell 
is specified in the registry) and sets the systype to sys5.3. 

ENVIRONMENT = aegis 
SYSTYPE = sys5.3 
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FILES 

/bin/csh 

/bin/ksh 

/bin/sh 

/etc/motd 

/etc/profile 

/etc/environ 

'/.sys type 

SEE ALSO 

environment 1 ), csh( l ), sh( I ), ksh( 1 ) 
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NAME 

Ipadmin - configure the line printer (LP) spooling system 
SYNOPSIS 

/usr/lib/lpadmin -p printer [ options ] 

/usr/lib/lpadmin -x dest 
/usr/lib/lpadmin -d [ dest ] 

DESCRIPTION 

Ipadmin configures line printer (LP) spooling systems to describe printers, classes, and 
devices. It adds and removes destinations, changes class membership, changes printer 
devices, changes printer interface programs, and changes system default destination. 
Ipadmin cannot be used when the LP scheduler, Ipsched(lM), is running, except where 
noted below. 

OPTIONS 

You must specify one of the -p, — x or — d options for each invocation of Ipadmin. 



— p printer 


Names a printer to which the options below refer. If printer does not 
exist, it is created. 


-\dest 


Removes destination dest from the LP system. If dest is a printer and is 
the only member of a class, then the class is also deleted. No other 
options are allowed with — x. 


-d [dest] 


Makes dest, an existing destination, the new system default destination. 
If you do not supply dest, there is no system default destination. This 
option can be used when Ipsehed(lM) is running. No other options are 
allowed with — d. 


The following options can only be used with — p and can appear in any order. For ease 
of discussion, the printer is referred to as P below. 


-c class 


Inserts printer P into the specified class, class is created if it does not 
exist. 


-e printer 


Copies an existing printer’s interface program to be the new interface 
program for P. 


-h 


Indicates that the device associated with P is hardwired. This option is 
assumed when you add a new printer unless you specify the —1 option. 


-i interface 


Establishes a new interface program for P. interface is the pathname of 
the new program. 


-1 


Indicates that the device associated with P is a login terminal. The LP 
scheduler, lpsched, disables all login terminals automatically each time 
it is started. Before re-enabling P, its current device should be esta- 
blished using Ipadmin. 


-m model 


Selects a model interface program for P. model is one of the model 
interface names supplied with the LP spooling utilities. 
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— r class Removes printer P from the specified class. If P is the last member of 
the class, the class is removed. 

—x device Associates a new device with printer P. device is the pathname of a file 
that is writable by Ip. 

Restrictions 

When you are creating a new printer, the -v option and one of the -e, -i or -m options 
must be supplied. Only one of -e, — i or -m can be supplied. The — h and -1 keyletters 
are mutually exclusive. Printer and class names can be no longer than 14 characters 
and must consist entirely of the characters A-Z, a-z, 0-9 and _ (underscore). 

Models 

Model printer-interface programs are supplied with the LP spooling utilities. They are 
shell procedures that interface between Ipsched and devices. All models reside in the 
directory /usr/spool/lp/model and can be used as is with Ipadmin -m. Copies of 
model interface programs can also be modified and then associated with printers using 
Ipadmin — i. The following describes the models that can be listed on the Ip command 
line using the — o keyletter: 

LQP-40 Letter quality printer using XON/XOFF protocol at 9600 baud. 

DQP-10 Dot matrix draft quality printer using XON/XOFF protocol at 9600 baud. 

NOTE 

The same device can be associated with more than one printer. If only the — p and — v 
options are supplied, Ipadmin can be used while the scheduler is running. 

EXAMPLES 

1. A DQP-10 printer named cI8, uses the DQP- 10 model interface after the command: 

/usr/lib/lpadmin -pcI8 -mdqplO 

2. A LQP-40 printer called prl is added to the lp configuration with the command: 

/usr/lib/lpadmin -pprl -v/dev/eexol -mlqp40 



FILES 

/usr/spool/l p/* 

(a link to //lp_site/usr/.spool/lp where spooling occurs) 

SEE ALSO 

accept( 1M), lpsched(lM). enable/ 1), lp(l), lpstat(l) 
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NAME 

1 protect - control local protection 
SYNOPSIS 

/etc/lprotect [-e rootlocal] [-d rootlocal] 

DESCRIPTION 

The 1 protect command controls local protection attributes on a node. Currently, this 
command enables requests by root (locksmith) to be honored only if they originate 
locally (rootlocal), i.e. from a local process. If no options are specified, the current 
state of rootlocal is returned. To change the state of the rootlocal attribute, you must 
be running as root (locksmith). 

OPTIONS 

-e rootlocal Enables local-only root requests. 

— d rootlocal Disables local-only root requests. 

EXAMPLE 

1. Show current status. 

$ /etc/lprotect 

"local-only root requests" is disabled, (-d rootlocal) 



2. Enable local root requests 

$ /etc/lprotect -e rootlocal 
$ /etc/lprotect 

"local-only root requests" is enabled. 



3. Disable local root requests 

$ /etc/lprotect -d rootlocal 
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NAME 

Ipsched, Ipshut, Ipmove - start/stop the line printer (LP) scheduler and move requests 

SYNOPSIS 

/usr/lib/lpsched 

/usr/lib/lpshut 

/usr/Iib/lpmove requests dest 
/usr/lib/lpmove dest l destl 

DESCRIPTION 

Ipsched schedules requests taken by lp(l) for printing on line printers (LP’s). 

Ipshut shuts down the line-printer scheduler. All printers that are printing when Ipshut 
is invoked stop printing. Requests that are printing when a printer shuts down are 
reprinted in their entirety when Ipsched is started again. 

Ipmove moves requests queued by lp( 1 ) between LP destinations. You can use Ipmove 
only when Ipsched is not running. 

The first form of the command moves named requests to the LP destination, dest. 
requests are "request ids" returned by lp(l). The second form moves all requests for 
destination destl to destination dest2. Ip(l) then rejects requests for destl . 

NOTE 

Ipmove never checks the acceptance status (see accept(lM)) for the new destination 
when moving requests. 

FILES 

/usr/spool/lp/* 

SEE ALSO 

accept(lM), lpadmin(lM), enable(l), lp(l), lpstat(l) 
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NAME 

mbd - dump usage info on tcp buffer pool 
SYNOPSIS 

/ete/mbd [ -f ] [ — k ] 

DESCRIPTION 

The mbd command dumps usage information about the tcp memory buffer pools. 
Usage statistics on tcp memory buffers may be obtained by using the -m option of the 
netstat command; mbd is intended for analyzing cases where buffers are being lost. It 
scans the entire buffer pool, finding all the chains of in-use buffers; it then prints each 
chain of buffers. This information may help you in discovering reasons why buffers are 
being lost. 

OPTIONS 

— f Dump the free pools as well as the chains of in-use buffers. This produces a lot 

of output. 

— k Don’t try to lock the mutex on the buffer pools before doing the dump. This is 

useful mostly when the tepd has crashed with the buffer pool mutex locked. 

EXAMPLES 

A dump of the buffer pools of a basically idle tcp might look like this: 



$ /etc/mbd 








Offset 


0x000035cc 


size 


1520 


type 


Offset 


0x000041cc 


size 


1520 


type 


Offset 


0x00003bcc 


size 


1520 


type 


Offset 


0x0000a7cc 


size 


1520 


type 


Offset 


0x00004dcc 


size 


1520 


type 


Offset 


0x00007dcc 


size 


1520 


type 



1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 


1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 


1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 


1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 


1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 


1 


off 


24 


len 


1512 


ref cnt 


1 


pool 


1 



Here there are 6 large (1520-byte) buffers in use, all on a single chain. 
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NAME 

mkcon — set console device 
SYNOPSIS 

/etc/mkcon [— p] [-d dev] [-c cmd] [— n] 

DESCRIPTION 

If no arguments are specified with this command, it makes the current controlling termi- 
nal into a console and starts up a shell. The shell type is determined by the shell 
environment variable. When the shell exits, the console output is redirected to 
, node_data/system_logs/console. 

OPTIONS 

-p Create a new DM pad for the console in place of the controlling terminal 

device. 

— d dev Make dev replace the controlling terminal device as console. 

— c cmd Execute cmd instead of $SHELL. 

— n Do not ran a shell. 

EXAMPLE 

$/etc/mkcon -d /dev/display -n 

This causes console output to appear in a DM window, with a new window each tune 
/dev/console is opened. 
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NAME 

mkdev - shell script to make devices 
SYNOPSIS 

mkdev device -directory [— d devno _jile] [all \ console \ tty \ null \ sio \ pad \ pty | 
dsk | mt | global devices | crp ] 

DESCRIPTION 

mkdev creates devices, device _directory is usually /dev; -d devno Jile can be used to 
specify a device number/manager mapping file to use in place of 
k node_data/device_n umbers. 

If no additional arguments are specified, then all devices which have not been created 
will be. mkdev creates a file called .mkdev in the device directory to record for future 
instances of itself what work has to be done, (actually just the version of the last mkdev 
to run to completion). 

If any arguments are specied (or all) then these devices will be deleted and recreated. 

DIAGNOSTICS 

Should be self-explanatory. 

FILES 

,, node_data/device_numbers Default device number mapping file 



Commands 



9-103 




MKDEVNO(IM) 



SysV 



MKDEVNO(IM) 



NAME 

/etc/mkdevno - assign mapping of major device number to a trait manager 
SYNOPSIS 

/etc/mkdevno -a [-n device jmmbersjle] type b|c [major] 

/etc/mkdevno -r [-n device numbers Jde] type b|c major 
/etc/mkdevno -d [-n device jiumbers Jde] type b|c major 
/etc/mkdevno -1 [-n device numbers Jle] 

DESCRIPTION 

mkdevno assigns mapping of a major device number to a trait manager. Note that this 
correspondence only applies to devices created (with mknod(lM)) while the mapping 
is in effect; if mkdevno is used to map a new manager to an existing device number 
this will not affect devices previously created. 

OPTIONS 

— n file Uses the named file instead of 

‘node_data/device_numbers 

-a Assigns a new mapping. 

-r Replaces an existing mapping. 

— d Deletes an existing mapping. 

-I Lists current mappings. 

OTHER PARAMETERS 

type The name or UID of the installed manager. 

b|c b for block special device, c for character special device. 

major Major device number (optional for assign operation). If not specified 

then lowest available number is used. This number should be in the 
range of 0-3 1 for character special devices and between 0-7 for block 
special devices. 

DIAGNOSTICS 

Should be self explanatory. 

FILES 

k node_data/device_numbers - default mapping file 
SEE ALSO 

mkdev(lM), mknod(lM) 
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NAME 

mkdisk - create disk-device descriptor files 
SYNOPSIS 

/ete/mkdisk [— S | -VV | — F] [— c number ] [— d number ] [—1 number ] [— r] devname 
DESCRIPTION 

mkdisk creates block and character special device files that describe disk devices 
attached to a node. 

SysV nodes currently support three types of disk-device. The conventional name for 
each type of disk is as follows: 

Winchester disks W 
Storage modules S 

Floppy disks F 

All disk descriptor files are usually kept in the /dev/dsk directory for block disk-device 
files and the /dev/rdsk directory for raw disk-device files. By convention, the names 
assigned to disk-device files on a SysV system include the disk type name as listed 
above, concatenated with a string denoting the drive number and a string denoting the 
logical volume number. Thus, for example, logical volume 1 of drive 0 of a storage 
module disk is conventionally named /dev/dsk/SOdOsl. In this case, the prefix 
/dev/dsk is the name of the directory where all block disk descriptor files nonnally 
reside; S indicates that this is a storage module disk; d<) denotes drive number 0, and si 
indicates that this is logical volume 1 (logical volumes on a physical drive are num- 
bered from 1). 

The UNIX operating system distinguishes between block and “raw” (character) dev- 
ices. Each disk has a block-device interface that makes the device byte-addressable. 
Raw devices are also available. Some UNIX systems place restrictions on the use of 
raw-devices (for example, on some systems, raw-devices must be read or written 512 
bytes at a time). No such restrictions currently exist on SysV raw devices; in general, 
raw and block-devices can be used interchangeably on SysV. 

Typically, there is a raw-device descriptor file and a block-device descriptor file for 
each disk on a SysV system. The raw-device descriptor file and the block device 
descriptor usually have the same name, with the block-device descriptor file located in 
the /dev/dsk directory and the raw-device descriptor file located in the /dev/rdsk direc- 
tory. 

If run with no options, mkdisk tries to figure out the disk type and unit numbers from 
the disk descriptor filename you supply, using the naming conventions described above. 

You can use mkdisk to create disk descriptor files whose names do not follow the con- 
ventions described above, by supplying the needed information in options. If an option 
is explicitly supplied, it overrides the information mkdisk deduces from the filename. 
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OPTIONS 



-s 


Disk is a storage module. 


-w 


Disk is a Winchester. 


-F 


Disk is a floppy disk. 


-c number 


Controller number. 


-d number 


Drive number. 


-1 number 


Logical volume number. 


-r 


Disk is raw. 



EXAMPLE 

/etc/mkdisk /dev/wnlc 

creates a block-device descriptor file for logical volume 3 
of drive 1 on the Winchester disk. 

DIAGNOSTICS 

The diagnostics are intended to be self-explanatory. 

SEE ALSO 

mount( 1 M ), umount( 1M) 
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NAME 

ink hosts - generate hashed host table 
SYNOPSIS 

/etc/mkhosts [ -v ] [ hostjile ] 

DESCRIPTION 

The mkhosts command is used to generate the hashed host database used by one ver- 
sion of the library routines gethostbyaddr(3N) and gethostbvname(3N) . It is not used 
if host name translation is performed by named ( I M). 

The new database is build in a set of temporary files and only replaces the real database 
if the new one is built without errors, mkhosts will exit with a non-zero exit code if 
any errors are detected. 

OPTIONS 

—v List each host as it is added. The default hostjile is /etc/hosts. If another 

file is specified, it must be in the format of /etc/hosts (see hosts(4)). 
mkhosts will generate database files named hostjile. pag and hostjile. dir. 

FILES 

hostjile. pag - real database filenames 
hostjile. dir 

hostjile. new.pag - temporary database filenames 
hostjile. new. dir 

SEE ALSO 

gethostbyname(3), gettable(lM), hosts(4), htable(lM), named(lM); 

Configuring and Managing TCP/IP. 
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NAME 

mknod - create a special file 
SYNOPSIS 

/etc/mknod name b | c major minor 
/etc/mknod name p 

DESCRIPTION 

mknod makes a directory entry and corresponding i-node for a special file. 

The first argument is the name of the entry. These files are kept in the /dev directory by 
convention. 

In the first case, the second argument is b if the special file is block-type (disks, tape) or 
c if it is character-type (other devices). The last two arguments are numbers specifying 
the major device type and the minor device (e.g., unit, drive, or line number). These 
may be specified in either decimal or octal. You must be the super-user to use this form 
of the command. 

The major device number given must correspond to a trait manager for the device. The 
mkdevno(lM) command creates a mapping between a major device number and a trait 
manager; this mapping must exist before a device node is created. Minor device 
numbers may be arbitrarily chosen, except that the minor number for a cloneable 
STREAMS device must be 256 decimal or higher (see clone(7)). 

The second case is the form of the mknod that is used to create FIFO’s (also known as 
named pipes). 

mknodx is a variation of mknod. This command is used by Apollo system administra- 
tors, and should not be deleted. 

NOTE 

If, under implementations supporting Remote File Sharing (RFS), mknod is used to 
create a device in a remote directory, the major and minor device numbers are inter- 
preted by the server. 

SEE ALSO 

mkdev(lM), mkdevno(lM), mknod(2), clone(7) 
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NAME 

mount, umount - mount and unmount file systems 
SYNOPSIS 

/etc/mount [[— r] directory ] 

/etc/umount special 

DESCRIPTION 

File systems other than root ( / ) are considered removable in the sense that they can be 
either available to users or unavailable, mount announces to the system that special, a 
block-special device is available to users from the from the mount-point directory, 
directory must already exist; it becomes the name of the root of the newly mounted 

special. 

mount, when entered with arguments, adds an entry to the table of mounted devices, 
/etc/mnttab. umount removes the entry. If invoked with no arguments, mount prints 
the entire mount table. If invoked with an incomplete argument list, mount searches 
/etc/fstab for the missing arguments. 

OPTIONS 

-r Indicates that special is to be mounted read-only. If special is write- 

protected, this flag must be used. 

special Indicates the block-special device that is to be mounted on directory. 

directory Indicates the directory mount-point for special. (The directory must 
already exist.) 

umount announces to the system that the file-system previously mounted special is to 
be made unavailable. If invoked with an incomplete argument list, umount searches 
/etc/fstab for the missing arguments. 

Anyone can use mount to list mounted file-systems. Only a super-user can mount and 
unmount file-systems. 

NOTE 

Physically removing a mounted file-system diskette from the diskette drive before issu- 
ing the umount command damages the file-system. 

FILES 

/etc/mnttab Mount table 

/etc/fstab File system table 
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DIAGNOSTICS 

If the mount(2) system call fails, mount prints an appropriate diagnostic, mount issues 
a warning if the file-system to be mounted is currently mounted under another name. 

umount fails if special or resource is not mounted or if it is busy, special or resource 
is busy if it contains an open file or some user’s working directory. In that case, you 
can use fuser( lM) to list and kill processes that are using special. 

SEE ALSO 

unadv(lM), mount(2), umount(2), fstab(4), mnttab(4) 
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NAME 

mvdir - move a directory 
SYNOPSIS 

/etc/mvdir dirname name 

DESCRIPTION 

mvdir moves directories within a file system, dirname must be a directory. If name 
does not exist, it is created as a directory. If name does exist, dirname is created as 
name! dirname . dirname and name cannot be on the same path; that is, one may not be 
subordinate to the other. 

EXAMPLE 

mvdir x/y x/z 
is legal, but 
mvdir x/y x/y/z 
is not. 

SEE ALSO 

mkdir(l), mv(l) 

NOTE 

Only the super-user can use mvdir. 
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NAME 

named — Internet domain name server 

SYNOPSIS 

named [ -d debuglevel ] [ -p port# ] [ bootfile ] 

DESCRIPTION 

named is the Internet domain name server (see RFC883 for more details). Without any 

arguments, named reads the default boot file /etc/named. boot, reads any initial data, 

and listens for queries. 

OPTIONS 

-d debuglevel Print debugging information. A number after the d determines the 
level of messages printed. 

-p port# Use a different port number. The default is the standard port number 

as listed in /etc/services. 

bootfile Any additional argument is taken as the name of the boot file. The 

boot file contains information about where the name server is to get its 
initial data. 

EXAMPLE 

The following example shows a boot file: 



boot file for name server 



; type 



domain 



source file or host 



domain 

primary 

secondary 

cache 



berkeley . edu 

berkeley.edu named, db 
cc.berkeley.edu 10.2.0.78 128.32.0.10 
named . ca 



The first line specifies that berkeley.edu is the domain for which the server is authorita- 
tive. The second line states that the file named. db contains authoritative data for the 
domain berkeley.edu. The file named. db contains data in the master file format 
described in RFC883, except that all domain names are relative to the origin; in this 
case, berkeley.edu (see below for a more detailed description). 

The third line specifies that all authoritative data under cc.berkeley.edu is to be 
transferred from the name server at 10.2.0.78. If the transfer fails it will try 128.32.0.10 
and continue trying the address, up to 10, listed on this line. The secondary copy is also 
authoritative for the specified domain. 
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The fourth line specifies data in nanied.ca is to be placed in the cache (i.e., well known 
data such as locations of root domain servers). The file named.ca is in the same format 
as named.db. 

MASTER FILE FORMAT 

The master file consists of entries of the form: 

$INCLUDE <filename> 

$ORIGIN <domain> 

<domain> <opt_ttl> <opt_class> <type> <resource record _data> 

where domain is dot “ for root, for the current origin, or a standard domain 

name. If domain is a standard domain name that does not end with the current ori- 
gin is appended to the domain. Domain names ending with are unmodified. The 
optjtl field is an optional integer number for the time-to-live field. It defaults to zero. 
The opt_ciass field is the object address type; currently only one type is supported, IN, 
for objects connected to the DARPA Internet. The type field is one of the following 
tokens; the data expected in the resource _record_data field is in parentheses. 

A A host address (dotted quad) 

NS An authoritative name server (domain) 

MX A mail exchanger (domain) 

CNAME The canonical name for an alias (domain) 

SOA Marks the start of a zone of authority (5 numbers (see RFC883)) 

MB A mailbox domain name (domain) 

MG A mail group member (domain) 

MR A mail rename domain name (domain) 

NULL A null resource record (no format or data) 

WKS A well known service description (not implemented yet) 

PTR A domain name pointer (domain) 

HINFO Host information (cpu_type OS_type) 

MINFO Mailbox or mail list infonnation (request_domain error_domain) 

NOTES 

The following signals have the specified effect when sent to the server process using the 
kill(l) command. 

SIGHUP Causes server to read named.boot and reload database. 

SIGINT Dumps current data base and cache to /usi7tmp/named_dump.db 
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SIGUSR1 Turns on debugging; each SIGUSR1 increments debug level. 
SIGUSR2 Turns off debugging completely. 

FILES 

/etc/named. boot name server configuration boot file 

/etc/named.conf configuration file 

/etc/named. pid the process id 

/usr/tmp/named.run debug output 

/usr/tmp/named_dump.db dump of the name servers database 

Configuration files read by /etc/named. boot: 

/etc/named .ca 
/etc/named. hosts 
/etc/named, local 
/etc/named, rev 

SEE ALSO 

kill(l), gethostbyname(3N), signal(3c); 

Configuring and Managing TCP/IP', 

RFC882, RFC883, RFC973, RFC974, Name Server Operations Guide for BIND. 
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NAME 

netmain - analyze network maintenance stats 
SYNOPSIS 

/etc/netmain [ options ] 

DESCRIPTION 

netmain is an interactive, menu-driven program that lets you control the netmain_srvr, 
the network maintenance server, and analyze the data that netmain_srvr produces, 
netmain provides detailed help from its menus. 

OPTIONS 

— w[help] (default) Make sure the window is large enough to display command menus 
and interactive help. 

-\vc[md] Set the window size smaller for command menus only. If you later 

decide that you want to see the helps, grow the window manually 
with <GROW>. 

-nw Do not change the window size. 

EXAMPLES 

1. Run netmain in a window large enough to display command menus and interactive 
help: 

$ /etc/netmain 

2. Run netmain in a window large enough (but no larger) to display the command 
menus: 

$ /etc/netmain -wc 
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NAME 

netmain_chkIog - clean up bad log files 
SYNOPSIS 

/etc/netmain_chklog [ options ] pathname... 

DESCRIPTION 

When the netmain_srvr program halts catastrophically (for instance, during a node 
reset), it can leave the log file it was writing in a corrupt, unusable state. 
netmain_chklog determines whether the log is corrupt and, optionally, deletes corrupt 
files. 

If the pathname you specify points to some kind of file other than a netmain log file, 
that file is almost always ignored; it is almost never deleted as a corrupt log. On very 
rare occasions, another kind of file may look so much like a corrupt log that it might be 
deleted accidentally if you use both -d and the standard command option -nq (no 
query). Thus you should use -d — nq with extreme care. 

pathname (required) Specify the files to be checked. Multiple names and wildcarding 

are permitted; separate names with blanks. 

OPTIONS 

— d Delete corrupt log files. 

— nd (default) Do not delete anything. 

—1 (default) Describe every file analyzed. 

— nl Describe only corrupt log files. 

EXAMPLES 

$ /etc/netmain_chklog ‘node data/net log/ * 



9-116 



Commands 




NETMAIN_NOTE( 1 M) 



Domain/OS SysV 



NETMAIN_NOTE( 1 M) 



NAME 

netmain_note - place message in network error log 

SYNOPSIS 

/etc/netmain_note string [string ...] 

DESCRIPTION 

netmain_note sends a text string to netmain_srvr, the network maintenance server. 

The message is broadcast to all maintenance servers. 

Typical topics of maintenance notes include known or explainable network failures, 

scheduled down-time, and node installations. 

string (required) Specify message to be sent. You may use any string that is legal 

in a shell command. (Note that the shell takes special action on 
some keywords, such as ’if’, unless you place them in quotation 
marks.) If there is more than one string, netmain builds the note 
by concatenating the arguments that are separated by spaces. 

EXAMPLES 

$ /etc/netmain_note ’Scheduled down time at 5 pm.’ 

$ /etc/netmain_note Cable disconnected at //sancho_panza 
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NAME 

netmain_srvr - collect network error stats 
SYNOPSIS 

/etc/netmain_srvr [options] [ pathname ] 

DESCRIPTION 

netmain_srvr collects and stores performance statistics for the Apollo token ring net- 
work. Use netmainsrvr to gather information; use the netmain program to display 
and analyze the information. 



You can set parameters for netmain_srvr from the command line and from an options 
file. Once the server is running, you can change any parameter using the netmain pro- 
gram. To include parameters in an options file, specify the — cmdf option. 

When you specify —cmdf pathname, netmain_srvr reads the options listed in the 
options file first and then reads any other options on the netmain_srvr command line. 
If options specified in the file and on the command line differ, netmainsrvr uses the 
command line settings. For example, if the options file specifies a log file length as —II 
1500, and the command line specifies —II 3000, netmain_srvr uses -II 3000. 



If a netmain_srvr does not start properly, a record of the failure appears in 
‘node_data/netmain_srvr.err_log. 



OPTIONS 

— a[ppend] Append to an existing log file with this name, if one already 

exists; otherwise, create a log file with this name. This option is 
only valid when a log file pathname is specified with the —I 
option. Contrast this with the -nappend option. 

-cmdf pathname Accept options from an ASCII text file pathname. You may use 

this option only from the command line, not in the options file. 
There can only be one options file. 

-l[og] [pathname] (default) 

Create a log file. Optionally, specify a pathname, which is rela- 
tive to the k node_data/net_log directory. If either this option or 
the pathname is not specified, the log file name is derived from 
the current date: ‘node_data/net_log/net_log.yy.mm.dd. The 
log file is stored on the disk of the node running netmainsrvr, 
and must remain there for netmain srvr to write to it. 



—II n (default) Set an upper limit on the length of the log file. The file size limit 

n is in 1024-byte units. The default value for n is 3000. You 
must use this option when you start the monitor and if you don’t 
want to use the default length for the first log file, since you can- 
not change the name of a log file once it’s open. 
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-nafppend] (default) 

Create a new log file, over-writing any log with that name, if one 
exists. This option is only valid when a log file pathname is 
specified with the —I option. Contrast this with the -append 
option. 

— nl [log] Do not write to a log file. netmain_srvr still runs probes and 

observers. 

-ntopo[_init] (default) 

Override the -topo_init option, if -topo_init is specified in an 
options file, -ntopo is useful only on the command line. 

-obs[erve] observer time ... 

Set the interval at which the named observer wakes up. Specify 
time as hh:mm:ss, hh:mm, or never, if you do not want the moni- 
tor to run the observer. Multiple observer/time pairs are permit- 
ted. See the default times listed below for each observer. 

— re_obs[erve] observer time ... 

Set the "Recheck interval” — the interval that the observer waits 
before rechecking a node that has caused an alarm condition. By 
setting a recheck interval, you ensure that the observer only 
reports on a node once every time period. If the recheck interval 
is too short, the observer may produce many redundant alarms. 
Specify time as hh:mm:ss, or hh:mm. Multiple observer/time 
pairs are permitted. See the default recheck intervals listed 
below for each observer. 

-s[ample] probe time ... 

Set the interval at which the named probe wakes up. Specify 
time as hh:mm:ss, hh:mm, or never, if you do not want the moni- 
tor to run the probe. Multiple probe/time pairs are permitted. 
See the default times listed below for each probe. 

-sk[ip] probe distance ... 

Set the skip distance for the probe named. If the skip distance is 
n, the named probe samples approximately 1 fn of the nodes every 
time it wakes up. Multiple probe/distance pairs are permitted. 
See the default skip distances listed below for each probe. 

— topo[_init 1 pathname 

Initialize the monitor’s total node list from a data file. The file 
may contain any number of node names or hexadecimal IDs, 
separated by spaces or on separate lines. If there is a "#" or "{" in 
any line, that character and all characters to the right of it are 
ignored (that is, "#" and "{" are comment markers). 
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NAME 

netsvc - set or display network services 

SYNOPSIS 

/etc/netsvc [options] 

DESCRIPTION 

netsvc sets or displays the network services that this node will perform. All changes 

take place immediately. 

OPTIONS 

If no options are specified, netsvc displays the network services allowed for this node. 

— n None. Disable all network services and physically disconnect this node 

from the network. 

-I Local. Allow only network requests originating at this node. 

— r Remote. Allow only network requests originating at other nodes. 

-a (default) All. Allow both locally and remotely initiated network requests. (The 
size of the remote paging pool is not changed.) 

— s[ervers] [«] Servers. Set the number of network servers to run on this node. At sys- 
tem startup, the number of network servers is 1. If this node is a network 
partner for diskless nodes or has several remote file users, their perfor- 
mance can be improved by increasing the number of servers. If n is not 
specified, the maximum number of servers (3) is used. 

— p [«] Pool. Set local memory pool size. Network page requests originating at 

remote nodes may not use more than n pages of the local node’s 
memory. If n is not specified, all the local node’s memory is eligible for 
remote page requests. 

-net [netjd] Network ID. Set or display network ID. Use this option to change or 
examine the ID of the network to which the node is attached. It affects 
only the node at which you type the command, not the rest of the net- 
work. Specifying a hexadecimal network ID changes your node’s net- 
work ID. Using -net with no argument forces netsvc to display your net- 
work ID even if it is set to 0. 

This option is useful only when there are no internet routers active on the 
node’s network. Routers give the network ID to nonrouting nodes every 
30 seconds, and may override the network ID you specify with this 
option. 
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NOTE 

If the network ID you set with —net differs from the network ID used by other nodes on 
your network, your node may not be able to communicate with those other nodes. 

Be careful when revoking network access with -n or -1. Remote file users may have 
problems, and writable files may be damaged. If your node was the network partner for 
a diskless node, that node will crash when your node leaves the network. 

Use the -s option carefully. Although you can increase the number of servers, you can- 
not decrease it. The only way to return to a smaller number of servers is to reboot the 
node. Also note that increasing the number of server processes decreases the number of 
user processes allowed. 

EXAMPLES 

$ /etc/netsvc 

Network operations allowed: ALL 
Number of network servers : 1 
Remotely initiated paging pool limit : NONE 
Network ID: 437A9 
$ 

SEE ALSO 

More information is available. Type 

help rtsvc For information about controlling a node’s internet routing service 
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NAME 

nodestat — display network statistics 
SYNOPSIS 

/etc/nodestat [options] 

DESCRIPTION 

writes a summary of network and hard disk activity to standard output. 

OPTIONS 

If no options are specified, nodestat returns a brief summary of network usage informa- 
tion for the current node. 



-I 

-eon fig 

-n node spec ... 
-a 

-r [n] 



-s [/tj 



— save pathname 
-since pathname 

EXAMPLES 

$ /etc/nodestat 



Long report-provides more information than the summary. 

Configuration report-displays only node-specific hardware infor- 
mation: CPU type, display type, etc. 

Provide information on specified node(s). Multiple node_spec 
strings are permitted; separate them with blanks. 

Report on all nodes in the network. 

Repeat the nodestat command every n seconds until halted by 
CTRL/Q. Only counts that have changed at each iteration are 
displayed, and the values represent the amount of change rather 
than absolute values. The default value for n is 10 seconds. 

Send n test messages to every node being listed (except the 
current node) before every repeat of the display. If this option is 
specified, — r must also be specified. This option provides a 
minimum amount of network activity during the wait time 
between nodestat repeats. The default value for n is 100 mes- 
sages. 

Save all statistics in the file named pathname. 

Display counts that have changed since statistics were saved in 
pathname. 



The node ID of this node is 1FB. 



**** Node 1FB **** //diskless_$0001Fb diskless to //anger 

Up since 1988/02/01 at 8:17:06 Up for 1 day 2 hours 58 mins 4 secs 
Net I/O: total= 94625 revs = 66912 xmits = 27713 

Winchester I/O: total= 0 reads= 0 writes= 0 {NOTE 1} 

System configured with 1.0 mb of memory. 
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$ /etc/nodestat -I 

The node ID of this node is 1FB . 

**** N OC i e 1FB **** //diskless_$0001Fb diskless to //anger 

Up since 1988/02/01 at 8:17:06 Up for 1 day 2 hours 58 mins 52 secs 
Net I/O: total= 94756 revs = 67010 xmits = 27746 

10436 page-in requests issued. 

6473 page-out requests issued. 

41134 page-in requests serviced. 

12139 page-out requests serviced. 

Detected concurrency violations -- read: 0 write: 0 



Xmit 


count 


27746 


Rev 


eor 


0 


NACKs 




272 


Rev 


crc 


767 


WACKs 




1639 


Rev 


timout 


0 


Token 


, inserted 


65 


Rev 


buserr 


0 


Xmit 


overrun 


0 


Rev 


overrun 


0 


Xmit 


Ack par 


3 


Rev 


xmit-err 


3042 


Xmit 


Bus error 


0 


Rev 


Modem err 


0 


Xmit 


timout 


90 


Rev 


Pkt error 


45 


Xmit 


Modem err 


0 


Rev 


hdr chksum 


0 


Xmit 


Pkt error 


377 


Rev 


Ack par 


10 



Delay switched OUT. 

Winchester I/O: total= 0 reads= 0 writes= 0 {NOTE 1} 

Not ready 0 Contrlr busy 0 

Seek error 0 Equip check 0 

Drive time out 0 Overrun 0 

CRC error percentage: 0.00% 

Last ring hardware failure detected by node 241 {NOTE 2} 

on 1988/02/02 at 10:05 
System configured with 1.0 mb of memory. 

A total of 0 ECCC errors were detected. 
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Notes on Examples 

1. Node 1FB is running diskless, hence the absence of Winchester disk I/O 
activity. 

2. At 10:05 A.M. on Feb. 2, 1988, the network cable was disturbed immediately 
upstream of node 241. This information, coupled with the network topology 
available from Icnode can help you pinpoint a hardware malfunction. 

SEE ALSO 

rtstat(lM) 
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NAME 

nshost - generate host tables from the name server 
SYNOPSIS 

nshost [ — f file ... ] [ -d domain ... ] [ — s server ] [ -o output-file ] [ -r ] 
DESCRIPTION 

The nshost command converts host and address information from name server 
configuration files (see named(lm)) or from running name server(s) into the /etc/hosts 
format (see hosts(4)) or into the /etc/named. hosts.rev (reverse pointer records) format. 

OPTIONS 

- (file 



-d domain 



— s server 

-r 

SEE ALSO 

hosts(4), hostns(lm), named(lm); 
Configuring and Managing TCP/IP. 



Search the file for Standard Resource Records specifying addresses (A) 
or aliases (CNAME); these are then written to the standard output or the 
specified output-file. You may specify more than one — f file option. 

Query a running name server for the specified domain (determined by 
looking in the file /etc/ resol v.conf) for this same infonnation. You may 
specify more than one — d option. See the — s option. 

Specify alternate servers. You may specify up to three — s options per — d 
option. 

Request the /etc/nanied. hosts.rev (reverse pointer records) format. 
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NAME 

obtv - set or display the type of an object 
SYNOPSIS 

/etc/obty ([object type] pathname... ) 

DESCRIPTION 

obtv is intended for system-level debugging use only. Misuse of this command can 
cause objects to become inaccessible and programs to behave incorrectly. 

pathname (required) Specify object whose type is to be set or displayed. Wildcarding 

of this pathname is permitted. 

object jype (optional) Specify new type setting, object type must be a known type; 

the Itv command lists the types currently defined on a volume. 

Executable files (output of compilers and binders) are obj, coff 
or unstruct. Most other binary files are rec. 



Default if omitted: display current type of pathname 



EXAMPLES 

The sequence of the following commands is significant. 
Display current object type: 



$ /etc/obty testfile 
"testfile" object type is nil. 



Set type to uasc: 

$ /etc/obty testfile uasc 



Display new object type: 

$ /etc/obty testfile 

"testfile" object type is uasc. 
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NAME 

ping - send ICMP ECHO_REQUEST packets to network hosts 
SYNOPSIS 

/etc/ ping [ —cl ] [ — r ] [ — v ] host [ packetsize ] [ count ] 

DESCRIPTION 

The DARPA Internet is a large and complex aggregation of network hardware, con- 
nected together by gateways. Tracking a single-point hardware or software failure can 
often be difficult. The ping program utilizes the ICMP protocol’s mandatory 
ECHO_REQUEST datagram to elicit an ICMP ECHO_RESPONSE from a host or 
gateway. ECHO_REQUEST datagrams (“pings”) have an IP and ICMP header, fol- 
lowed by a struct timeval, and then an arbitrary number of “pad” bytes used to fill out 
the packet. Default datagram length is 64 bytes, but this may be changed using the 
command-line option. 

When using ping for fault isolation, you should first run it on the local host, to verify 
that the local network interface is up and running. Then, hosts and gateways further 
and further away should be “pinged”, ping sends one datagram per second, and prints 
one line of output for every ECHO_RESPONSE returned. No output is produced if 
there is no response. If you specify an optional count, only that number of requests is 
sent. Round-trip times and packet loss statistics are computed. When all responses 
have been received or the program times out (with a count specified), or if the program 
is terminated with a SIGINT, ping displays a brief summary. 

This program is intended for use in network testing, measurement and management. It 
should be used primarily for manual fault isolation. Because of the load it could 
impose on the network, it is unwise to use ping during normal operations or from 
automated scripts. 

OPTIONS 

Other options are: 

— d Display debugging infonnation. 

— r Bypass the nonnal routing tables and send directly to a host on an attached net- 

work. If the host is not on a directly-attached network, an error is returned. 
This option can be used to ping a local host through an interface that has no 
route through it (e.g., after the interface was dropped by routed(lM). 

—v Verbose output. List ICMP packets other than ECHO RESPONSE that are 
received. 

SEE ALSO 

ifconfig(lM), netstat(l); 

Configuring and Managing TCP/IP. 
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NAME 

probenet - probe network and display error statistics 
SYNOPSIS 

/etc/probenet [options] 

DESCRIPTION 

This command broadcasts packets to the diagnostic socket in all nodes, then requests 

error counts indicating the status the broadcast was received with. It compiles counts 

from every node in the topology list and reports them to standard output. 

OPTIONS 

Use one of the following three options to specify the list of nodes to display: 

-a (default) Probe all nodes responding to a /com/lcnode command. If the network 
is completely corrupted so that messages cannot make a complete pass, 
use one of the other two options to specify precisely which nodes to test. 

— t pathname Probe the nodes listed in the topology file indicated. The file must con- 
tain one hexadecimal node ID per line. Any text following a space after 
the node ID is ignored. You can insert comment lines if they are prefixed 
with a”#" or 

— n node id ... Probe the node(s) specified by the indicated hexadecimal node ID(s). A 
good choice of nodes to test is a set evenly spaced around the network. 

Use the following options to specify which test to run: 

— s n (default) Specify the total number of packets to be sent to each node. The default 
number of packets is 10. If 0 is specified for n, no test messages are sent, 
but statistics from each node are collected. 

-r [n] Repeat the probenet cycle every n seconds. If n is omitted, the cycle is 

repeated every 10 seconds. When you press <RETURN> at the input 
window, the send cycle is terminated immediately and the statistics are 
gathered and reported. 

Use the following options to specify which packets are sent: 

-d datajile Specify that the packets are taken out of the specified data file instead of 
the standard built-in data pattern. 

— len n (default) 

Specify the length (in bytes) of the data portion of the test packet, in 
bytes. The default length is 1024 bytes. 

Use the following options to control the level of detail in the statistics report. 

-I Print long (detailed) error counts if there were any errors (that is, at least 

one transmit error (xmit errs) or receive error (rev errs). 

-err Print header for each test, but statistics only for nodes which returned 

errors (xmit and/or rev errs). 
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-mon fail Jim 

Print header for each pass, but statistics only on passes whose total 
failure count equal or exceed the fail Jim value. 

-sens threshold 

Open a window pane and select some output lines to append to this pane. 
The nodes selected are those whose error count exceed a five-node run- 
ning average error count by the specified threshold value. Also, all nodes 
with modem errors are appended to this pane. The use of this secondary 
output is to do some data reduction and pick the nodes at or near points 
of data corruption in the network. The window pane is also stored in a 
named pad file called probenet.pane. 

EXAMPLES 

1. $ /etc/probenet (Probe entire network once. No errors detected.) 

There are 5 nodes in the test. 

Broadcasting 10 1024-byte packets . 85/02/20 21:16:52 # failures = 0 

Last Biph hardware failure detected by node 676 on 85/02/20 at 19:15 



MODEM 



NODE 


NAME 


ATTEMPT 


ERRS 


ERRS 


BIPH 


ESB 


TOKENS^ 0 


584 


^diskless 


10 


0 


0 


0 


0 


0 Self 


21 


OS 


10 


0 


0 


0 


0 


0 


AEF 


BS 


10 


0 


0 


0 


0 


0 


4A 


HUBRIS 


10 


0 


0 


0 


0 


0 


3536 


^diskless 


10 


0 


0 


0 


0 


0 
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2. $ probenet -t node list -s 14400 -r 3600 -d data_e3 

(Probes network and displays nodes specified in file "node_list". This node broadcasts 14400 
packets in 3600 seconds, that is, four packets per second. The packet data comes out of file 
"data_e3".) 



There are 5 nodes in the test. 

Broadcasting 14400 1024-byte packets (page 0) over 3600 seconds. 

85/02/20 21:58:19 # failures = 100 

Last Biph hardware failure detected by node 506 on 85/02/20 at 21:50 



MODEM 



NODE 


NAME 


ATTEMPT 


ERRS 


ERRS 


BIPH 


ESB 


TOKEN S= 3 


1967 


GTX 


14386 


0 


0 


0 


0 


1 Self 


15F5 


SWI 


14386 


0 


0 


0 


0 


0 


2255 


BIRDIE 


14384 


0 


0 


0 


0 


1 


3FD 


FLASH 


14386 


3 


3 


3 


0 


0 


2B69 


STANG 


14385 


3 


0 


0 


0 


1 


Broadcasting 14400 


1024-byte 


packets 


(page 


0) over 


3600 


seconds . 


85/02/20 21:58: 


: 41 # failures = 


100 








Last ] 


Biph hardware 


failure detected 


by node 


50 6 on 


85/02/20 at 21:50 
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NODE 


NAME 


ATTEMPT 


ERRS 


ERRS 


BIPH 


ESB 


TOKENS= 3 


1967 


GTX 


14383 


0 


0 


0 


0 


1 Self 


15F5 


SWI 


14383 


0 


0 


0 


0 


0 


2255 


BIRDIE 


14381 


0 


0 


0 


0 


1 


3FD 


FLASH 


14383 


4 


4 


4 


0 


0 


2B69 


STANG 


14382 


4 


0 


0 


0 


1 



(The example above shows a problem between node 3FD and its predecessor in the network.) 
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NAME 

pvvck, grpck - password/group file checkers 

SYNOPSIS 

/etc/pvvck [ file ] 

/etc/grpck [ file ] 

DESCRIPTION 

pwck scans the password file and notes any inconsistencies. The checks include valida- 
tion of the number of fields, login name, user ID, group ID, and whether the login direc- 
tory and the program-to-use-as-shell exist. The default password file is /etc/pass wd. 

grpck verifies all entries in the group file. This verification includes a check of the 
number of fields, group name, group ID, and whether all login names appear in the pass- 
word file. The default group file is /etc/group. 

FILES 

/etc/group 

/etc/passwd 

DIAGNOSTICS 

Group entries in /etc/group with no login names are flagged. 

SEE ALSO 

group(4), passwd(4) 



Commands 



9-131 




RC(1M) 



SysV 



RC(1M) 



NAME 

rc, rc. local, rc.user - command scripts for auto-reboot and daemons 

SYNOPSIS 

/etc/rc 

/etc/rc.local 

/etc/rc.user 

DESCRIPTION 

The rc command script controls the automatic reboot, the rc.local script contains com- 
mands that are pertinent only to a specific site, and the rc.user script contains com- 
mands used to start Domain/OS SysV daemons, such as mbx_helper, netman, prsvr, 
and spin. 

rc is run after an auto-reboot succeeds, rc starts the daemons on the system, preserves 
editor files, and clears the scratch directory /tmp. 

rc.local is executed immediately before any other commands. Normally, the first com- 
mands placed in the rc.local file define the machine’s name, using hostname(l). 

The rc script invokes rc.user and runs it as user.none.none. To start up the servers 
listed in the rc.user file, uncomment the appropriate lines in that file. 

NOTES 

The /etc/rc, /etc/rc.local, and /etc/rc.user files are links, which resolve to 
node_data/etc/rc, node_data/etc/ rc.local, and node_data/etc/ rc.user respectively. 

The /etc/rc file is owned by root, and protected such that only root can write to it. 

SEE ALSO 

init(8), reboot (8) 
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NAME 

rexecd - remote execution server 

SYNOPSIS 

/etc/rexecd 

DESCRIPTION 

rexecd is the server for the rexec(3) routine. The server provides remote execution 
facilities with authentication based on user names and passwords. 

The rexecd server listens for service requests at the port indicated in the “exec” ser- 
vice specification; see services(4). When a service request is received the following 
protocol is initiated: 

1) The server reads characters from the socket up to a null (‘\0’) byte. The resul- 
tant string is interpreted as an ASCII number, base 10. 

2) If the number received in step 1 is non-zero, it is interpreted as the port number 
of a secondary stream to be used for the stderr. A second connection is then 
created to the specified port on the client’s machine. 

3) A null terminated user name of at most 16 characters is retrieved on the initial 
socket. 

4) A null terminated, unencrypted password of at most 16 characters is retrieved 
on the initial socket. 

5) A null terminated command to be passed to a shell is retrieved on the initial 
socket. The length of the command is limited by the upper bound on the size 
of the system’s argument list. 

6) rexecd then validates the user as is done at login time and, if the authentication 
was successful, changes to the user’s home directory, and establishes the user 
and group protections of the user. If any of these steps fail the connection is 
aborted with a diagnostic message returned. 

7) A null byte is returned on the initial socket and the command line is passed to 
the normal login shell of the user. The shell inherits the network connections 
established by rexecd. 

DIAGNOSTICS 

Except for the last one listed below, all diagnostic messages are returned on the initial 
socket, after which any network connections are closed. An error is indicated by a lead- 
ing byte with a value of 1 (0 is returned in step 7 above upon successful completion of 
all the steps prior to the command execution). 

username too long 

The name is longer than 16 characters. 

password too long 

The password is longer than 16 characters. 
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command too long 

The command line passed exceeds the size of the argument last (as 
configured into the system). 

Login incorrect 

No password file entry for the user name existed. 

Password incorrect 

The wrong was password supplied. 

No remote directory 

The chdir command to the home directory failed. 

Try again A fork by the server failed. 

<shellname>: . . . 

The user’s login shell could not be started. This message is returned on 
the connection associated with the stderr, and is not preceded by a flag 
byte. 

BUGS 

Indicating “Login incorrect’’ as opposed to “Password incorrect’’ is a security breach 
which allows people to probe a system for users with null passwords. 

A facility to allow all data and password exchanges to be encrypted should be present. 

SEE ALSO 

rexec (3) 
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NAME 

/etc/rgv_admin - registry server administrative tool 

SYNOPSIS 

/ete/rgy_admin 

DESCRIPTION 

The rgv_admin tool administers registry servers. It can view or modify the registry 
replica list, reinitialize replicas, delete replicas, stop servers, and change the registry 
master site. 

Note that rgy_admin cannot add, delete, or modify data entries contained in the regis- 
try database, such as names and accounts; use edrgv to perform these tasks. To create a 
registry replica or to restart a server, use rgyd, the registry daemon. 

Once invoked, rgy_admin enters an interactive mode in which it accepts the commands 
described in the next section. 

COMMANDS 

Most rgy_admin commands operate on a default host. You use the set command to 
establish the default host, which is remembered until changed by another set. In the 
following command descriptions, we identify the default host as defaultjiost. If a com- 
mand operates on a host other than the default, we identify this host as other host. 

Several of the rgy_admin commands require you to set the default host to the master 
registry site. 

The host name you supply as a default _host or other Jiost takes the form family.host or 
host. The only currently supported family is dels, the Domain protocol family. You can 
specify a host in this family by its entry directory or by its network address. For exam- 
ple, dds://elara, //elara, dds:#!234.abcd, and #1234.abcd are all acceptable host 
names. 

become [ -master J [ -slave ] [ -ro | -\vr ] 

The -master option causes the replica at defaultjiost (which must be a 
slave replica) to become the master. This operation can cause updates to 
be lost; the changejmaster command is the preferred means of desig- 
nating a different master replica. 

The -slave option causes the replica at defaultjiost (which must be the 
master replica) to become a slave. This operation can cause updates to 
be lost; the change_master command is the preferred means of desig- 
nating a different master replica. 

The -ro option makes the replica list read-only. The defaultjiost must 
be set to the master registry site. 

The — wr option makes the replica list writable. The default host must 
be set to the master registry site. 
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changemaster -to other _host 

Change the master replica of the registry from default _host to 
other host. The default Jiost must be set to the master registry site. 

The current master server copies its database to the replica at other Jiost, 
becomes a slave, then tells the replica at other _host to become the mas- 
ter. i 

delrep other host [ -force ] 

Delete the registry replica at other host. The default Jxost must be set to 
the master registry site. 

The master server marks the replica at other _host as deleted and pro- 
pagates the deletion to all other replicas on its list. When it has actually 
delivered the delete request to the replica at other Jiost, the master server 
removes that replica from its own replica list. 

The -force option causes a more drastic delete. It deletes other Jiost 
from the replica list at the master registry, which then propagates the 
delete request to the replicas at the hosts that remain on its list. Since 
this operation never communicates with the deleted replica, you should 
use —force only when the replica has died irrecoverably. If you use 
—force while the replica at other Jiost is still running, you should then 
reset the deleted replica. 

help List the rgy_admin commands and show their allowed abbreviations, 

info Get status information about the replica at default Jiost. 

initrep other Jiost 

Reinitialize the registry server at other Jiost. The default Jiost must be 
set to the master registry site. The other Jiost must be a slave site. 

The master registry copies its entire database (or that of another up-to- 
date replica) to the replica at other host. 

I rep [ -state ] [ -na ] 

List the registry replica sites as stored in the replica list at default Jiost . 
The —state option shows the current state and update time on each host. 
The -na option shows the network address of each host. 

monitor [ -r m ] 

Periodically list the registry replica sites as stored in the replica list at 
default host and show the current state and update time at each site. 

The — r option causes the sites to be listed every m minutes. If you omit 
this option, the period is 15 minutes. 

quit Quit the rgy admin session. 
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reprep other host 

Replace the network address for other host in the registry replica list. 
The default Jiost must be set to the master registry site. 

The master replica propagates the new network address for other _host to 
all other registry replica lists. Use this command only if a replica site’s 
network number changes. 

reset other _host 

Reset the registry replica at other Jiost. The registry server at other host 
deletes its copy of the registry and stops running. This command does 
not delete other Jiost from any replica lists. 

set [ — h host name | -m ] 

Set the default host. Subsequent commands that do not specify a host 
will go to this host. 

The — h option specifies a replica to use as the default. 

The — m option causes the master replica to be the default. 

With no options, set locates a registry replica and sets it as the default, 
site [ hostjiame ] 

If hostjiame is specified, the command sets the default host. 

If host name is not specified, the command gets status information about 

default Jiost. 

state -inmaintenance | -notinniaintenance 

Put the master registry server into maintenance state or take it out of 
maintenance state. The default Jiost must be set to the master registry 
site. 

With the — in_maintenance flag, state causes the master registry server 
to save its database onto disk and refuse any updates. 

With the -not in niaintenance flag, state causes the master registry 
server to reload its database from disk, return to its normal "in service" 
state, and (if its database and/or replica list are writable) start accepting 
updates. 

stop Stop the registry server that is running at default Jiost. 
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EXAMPLES 

Start rgy_admin, list the replicas and their states, then set the default host to the master 
replica: 

$ /etc/rgy_admin 

Default object: rgy default host: dds://george 
State: in service slave 
rgy_admin: lrep — st 

(master) dds : / /martha state: in service 1987/11/16.12:46:59 
dds : //george state: in service 1987/11/16.12:46:59 
dds : / /thomas state: in service 1987/11/16.12:46:59 
rgy_admin: set— m 

Default object: rgy default host: dds: //martha 
State: in service master replica list is writeable 
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NAME 

rgy_create - registry creation utility 

SYNOPSIS 

rgyereate 

DESCRIPTION 

The rgyc reate tool creates a new registry database on the local node, initialized with 
reserved names and accounts. It ordinarily should be run only once at a site. Replicas 
of the database are created by running rgyd with the —create option. 

You must be root to invoke rgy_create. 

Note that to convert a pre-SRIO registry to SR 10 format, you should run only the 
cvtrgy tool, and you will never need to use rgy_create. 
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NAME 

rgymerge - merge registry database 
SYNOPSIS 

rgy merge -from llsite [ { -merge | -compare } -verbose ] 

DESCRIPTION 

The rgy_merge utility merges the contents of two registry databases, a source database 
and a target database. You typically use it when you are joining two networks that have 
been operating separately and you want to combine their registry databases. 

You must invoke rgv_merge while logged in as root at the master registry node for the 
target registry. Use the required —from //site argument to specify the master registry 
node for the source registry. The merge takes less time if the source database is smaller 
than the target database. 

After you invoke rgy_merge, the tool prompts you to "login" with an account that 
owns the source registry. 

Without a -merge or -compare option, rgy_merge attempts to add each entry in the 
source database to a copy of the target database and reports any conflicts in names or 
UNIX numbers. If there are no conflicts or errors, the tools asks whether you want to 
actually update the target database. If you respond affirmatively, it performs the merge 
on the target database and makes all replicas of the source registry slave replicas of the 
target registry. 

If you specify -merge, rgy_merge performs the merge without querying you, provided 
there are no conflicts or errors. If you specify —compare, rgy_merge only checks for 
conflicts and does not perform a merge even if there are none. 

The -verbose option causes rgy_merge to generate a verbose transcript of its activity. 
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NAME 

rgyd - network registry server 
SYNOPSIS 

/etc/rgyd [-create|-recreate|-restore_master] 

DESCRIPTION 

rgyd is the network registry daemon. It manages all access to the network registry 
database. You must be the super-user to invoke rgyd. 

The daemon can be replicated, so that several copies of the database exist on a network 
or an internet, each managed by a rgyd process. Only one registry daemon, the master, 
can accept operations that change the database (such as adding an account). If the dae- 
mon is replicated, the other replicas are slaves, which accept only lookup operations 
(such as validating a login attempt). 

A Local Location Broker daemon (llbd) must be running on the local node when rgyd 
is started. Typically, both daemons are started at boot time from /etc/rc. The server 
will place itself in the background when it is ready to service requests. 

OPTIONS 

-create Create a replica of the network registry. This option creates a copy 

of the registry database and starts a slave server process. You use 
-create only the first time you start a slave server process on a node. 
When you restart the daemon, you do not need any options at all. To 
create the master replica, use either cvtrgy (if you are converting an 
SR9 registry to SR10 format) or rgv_create (if you are creating a 
new SR 10 registry). 

-recreate Recreate a slave replica. You should use this option only if a slave’s 

copy of the database has been irreparably corrupted. It destroys the 
existing database and creates a new one. 

— restore_master Restart a master server and reinitialize all slave replicas. You should 
use this option only to recover from a catastrophic failure of the mas- 
ter node, (for example, if the database has been corrupted and then 
restored from a backup tape). 

EXAMPLES 

All of the commands shown in these examples must be ran by root. 

1. Start the master replica of the registry after you have created the master database 
via rgy create or cvtrgy: 

$ /etc/server -p /etc/rgyd 

2. Start a slave replica of the registry. 

$ /etc/server -p /etc/rgyd -create 
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3 . 



4 . 



Domain/OS SysV 

Restart an existing replica (master or slave) of the registry. 

$ /etc/server -p /etc/rgyd 

Restart an existing replica of the registry on the remote host //yak. 
$ /etc/crp -on //yak -cps -n rgyd //yak/etc/rgyd 
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NAME 

rlogind - remote login server 

SYNOPSIS 

/etc/ rlogind [ -d ] 

DESCRIPTION 

rlogind is the server for the rlogin(lC) program. The server provides a remote login 
facility with authentication based on privileged port numbers from trusted hosts. 

rlogind listens for service requests at the port indicated in the “login” service 
specification; see services(4). When a service request is received the following proto- 
col is initiated: 

1) The server checks the client’s source port. If the port is not in the range 0- 
1023, the server aborts the connection. 

2) The server checks the client’s source address and requests the corresponding 
host name (see gethostbyaddr(3N), hosts(4) and named(lM)). If the host- 
name cannot be determined, the dot-notation representation of the host address 
is used. 

Once the source port and address have been checked, rlogind allocates a pseudotermi- 
nal (see pty(7)), and manipulates file descriptors so that the slave half of the pseudoter- 
minal becomes the stdin, stdout, and stderr for a login process. The login process is 
an instance of the login(l ) program, invoked with the — r option. The login process then 
proceeds with the authentication process as described in rshd(lM), but if automatic 
authentication fails, it reprompts the user to log in as one finds on a standard terminal 
line. 

The parent of the login process manipulates the master side of the pseudoterminal, 
operating as an intermediary between the login process and the client instance of the 
'login program. In normal operation, the packet protocol described in ptv(7) is 
invoked to provide CTRL/S and CTRL/Q type facilities and propagate interrupt signals 
to the remote programs. The login process propagates the client tenninal’s baud rate 
and terminal type, as found in the environment variable, “TERM”; see environ(5). 
The screen or window size of the tenninal is requested from the client, and window size 
changes from the client are propagated to the pseudotemiinal. 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after 
which any network connections are closed. An error is indicated by a leading byte with 
a value of 1 . 

Try again. 

A fork by the server failed. 

/bin/ sh: ... 

The user’s login shell could not be started. 
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BUGS 

The authentication procedure used here assumes the integrity of each client machine 
and the connecting medium. This is insecure, but is useful in an “open” environment. 

A facility to allow all data exchanges to be encrypted should be present. 

A more extensible protocol should be used. 
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NAME 

route - manually manipulate the routing tables 
SYNOPSIS 

/etc/route [— f] [-n] [command args\ 

DESCRIPTION 

route is a program used to manually manipulate the network routing tables. It normally 
is not needed, as the system routing table management daemon, routed(lM), should 
tend to this task. 

route accepts three commands: add, to add a route; addp, to add a priority route; and 
delete, to delete a route. 

The addp command adds a priority route. The TCP/IP server process will use priority 
routes before default routes or routes established by routed(lM). A route added with 
addp will appear first in the gateway table (displayed with the SysV command netstat 
-r(l)). You can only add priority routes with addp. Routes added manually by route 
cannot be deleted by routed(lM). 

COMMAND SYNTAX 

All commands have the following syntax: 

/etc/route command [ net | host ] destination gateway [ metric ] 

where destination is the destination host or network, gateway is the next-hop gateway 
to which packets should be addressed, and metric is a count indicating the number of 
hops to the destination . The metric is required for add and addp commands; it must be 
zero if the destination is on a directly-attached network, and nonzero if the route utilizes 
one or more gateways. If adding a route with metric 0, the gateway given is the address 
of this host on the common network, indicating the interface to be used for transmis- 
sion. 

Routes to a particular host are distinguished from those to a network by interpreting the 
Internet address associated with destination . The optional keywords net and host force 
the destination to be interpreted as a network or a host, respectively. If the destination 
has a “local address part” of INADDR_ANY, or if the destination is the symbolic 
name of a network, then the route is assumed to be to a network; otherwise, it is 
presumed to be a route to a host. 

If the route is to a destination connected through a gateway, the metric should be 
greater than 0. All symbolic names specified for a destination or gateway are looked up 
first as a host name using gethostbyname(3N). If this lookup fails, getnetbyname(3N) 
is then used to interpret the name as that of a network. 

You can add a default route as follows: 

/etc/route add default gateway name [ non-zero metric ] 
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TCP/IP software will use the default route when other routes occuring earlier in the 
routing table have failed, or when there are no other possible routes. 

route uses a raw socket and the SIOCADDRT and SIOCDELRT ioctl’s(2) to do its 
work. As such, only the super-user may modify the routing tables. 

OPTIONS 
-f 



-n 

DIAGNOSTICS 

add [ host | network ] %s: gateway %s flags %x 

The specified route is being added to the tables. The values printed are 
from the routing table entry supplied in the ioctl(2) call. If the gateway 
address used was not the primary address of the gateway (the first one 
returned by get host byname(3N)), the 

gateway address is printed numerically as well as symbolically. 

delete [ host | network ] %s : gateway %s flags %x 
As above, but when deleting an entry. 

%s %s done 

When the — f flag is specified, each routing table entry deleted is indi- 
cated with a message of this form. 

Network is unreachable 

An attempt to add a route failed because the gateway listed was not on a 
directly-connected network. The next-hop gateway must be given. 

not in table 

A delete operation was attempted for an entry that wasn’t present in the 
tables. 

routing table overflow 

An add operation was attempted, but the system was low on resources 
and was unable to allocate memory to create the new entry. 

SEE ALSO 

routed(lM); 

Configuring and Managing TCPIIP. 



“Flush” the routing tables of all gateway entries. Using this option in con- 
junction with one of the commands described above flushes the tables prior 
to the command's application. 

Suppress printing symbolic host and network names when reporting actions. 
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NAME 

routed - network routing daemon 
SYNOPSIS 

/etc/routed [ -g j [ -s ] [ -q ] [ -t ] [ -n ] [ -f ] [ -h ] [ logfife ] 

DESCRIPTION 

The routed daemon is invoked at boot time to manage the network routing tables. The 
routing daemon uses a variant of the Xerox NS Routing Information Protocol in main- 
taining up to date kernel routing table entries. It uses a generalized protocol capable of 
use with multiple address types, but is currently used only for Internet routing within a 
cluster of networks. 

In normal operation routed listens on the udp(7) socket for the route service (see ser- 
vices^)) for routing information packets. If the host is an internetwork router, it 
periodically supplies copies of its routing tables to any directly connected hosts and net- 
works. 

When routed is started, it uses the SIOCGIFCONF ioctl(2) to find those directly con- 
nected interfaces configured into the system and marked “up” (the software loopback 
interface is ignored). If multiple interfaces are present, it is assumed that the host will 
forward packets between networks, routed then transmits a request packet on each 
interface (using a broadcast packet if the interface supports it) and enters a loop, listen- 
ing for request and response packets from other hosts. 

When a request packet is received, routed formulates a reply based on the information 
maintained in its internal tables. The response packet generated contains a list of 
known routes, each marked with a “hop count” metric (a count of 16, or greater, is 
considered “infinite”). The metric associated with each route returned provides a 
metric relative to the sender . 

Response packets received by routed are used to update the routing tables if one of the 
following conditions is satisfied: 

1 ) No routing table entry exists for the destination network or host, and the metric 
indicates the destination is “reachable” (i.e. the “hop count” is not infinite). 

2) The source host of the packet is the same as the router in the existing routing 
table entry. That is, updated infonnation is being received from the very inter- 
network router through which packets for the destination are being routed. 

3) The existing entry in the routing table has not been updated for some time 
(defined to be 90 seconds) and the route is at least as cost effective as the 
current route. 

4) The new route describes a shorter route to the destination than the one 
currently stored in the routing tables; to decide this, the metric of the new route 
is compared against the one stored in the table. 
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When an update is applied, routed records the change in its internal tables. The change 
is reflected in the next response packet sent. 

In addition to processing incoming packets, routed also checks the routing table entries 
periodically. If an entry has not been updated for 3 minutes, the entry’s metric is set to 
infinity and marked for deletion. Deletions are delayed an additional 60 seconds to 
ensure that the invalidation is propagated throughout the local internet. 

Hosts acting as internetwork routers gratuitously supply their routing tables every 30 
seconds to all directly connected hosts and networks. The response is sent to the broad- 
cast address on nets capable of that function, to the destination address on point-to- 
point links, and to the router’s own address on other networks. The normal routing 
tables are bypassed when sending gratuitous responses. The reception of responses on 
each network is used to determine that the network and interface are functioning 
correctly. If no response is received on an interface, another route may be chosen to 
route around the interface, or the route may be dropped if no alternative is available. 

OPTIONS 

routed supports several options: 

— g This flag is used on internetwork routers to offer a route to the “default” 

destination. This option is typically used on a gateway to the Internet, or 
on a gateway that uses another routing protocol whose routes are not 
reported to other local routers. 

-s Forces routed to supply routing information whether it is acting as an 

internetwork router or not. This is the default if multiple network inter- 
faces are present, or if a point-to-point link is in use. 

— q This option is the opposite of the — s option. 

— t If the — t option is specified, all packets sent or received are printed on 

the standard output. In addition, routed will not divorce itself from the 
controlling terminal, so that interrupts from the keyboard will kill the 
process. 

— d Not supported by Domain/OS SysV. 

Domain/OS SysV EXTENSIONS 

— n Directs routed not to install changes into the local routing table. How- 

ever, the routed process continues to receive broadcasts from other 
routed processes. The -n option is used for debugging purposes. 

— f Directs routed at startup to “flush” (purge) all routes from the local 

routing table, except routes added manually with /etc/route(lM). 

— h Exit, if not supplier, when routing table is stable. Use this switch on 

hosts only, not on gateways. 

Any other argument supplied is interpreted as the name of the file in which routed ’s 
actions should be logged. This log contains information about any changes to the 
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routing tables and, if not tracing all packets, a history of recent messages sent and 
received which are related to the changed route. 

In addition to the facilities described above, routed supports the notion of distant pas- 
sive and active gateways. When routed is started up, it reads the file /etc/gateways to 
find gateways that may not be located using only information from the SIOGIFCONF 
ioctl(2). Gateways specified in this manner should be marked passive if they are not 
expected to exchange routing information, while gateways marked active should be wil- 
ling to exchange routing information (that is, they should have a routed process run- 
ning on the machine). 

Passive gateways are maintained in the routing tables forever, and information regard- 
ing their existence is included in any routing information transmitted. Active gateways 
are treated equally to network interfaces. Routing information is distributed to the gate- 
way and if no routing information is received for a period of the time, the associated 
route is deleted. External gateways are also passive, but they are not placed in the rout- 
ing table nor are they included in routing updates The function of external entries is to 
inform routed that another routing process will install such a route, and that alternate 
routes to that destination should not be installed. Such entries are only required when 
both routers may learn of routes to the same destination. 

The /etc/gateways file is comprised of a series of lines, each in the following format: 

< net | host > name 1 gateway name2 metric value < passive | active | external > 

The net or host keyword indicates if the route is to a network or specific host. 

Namel The name of the destination network or host. This may be a symbolic 

name located in /etc/networks or /etc/hosts (or, if started after 
named(lM), known to the name server), or an Internet address specified 
in “dot” notation; see inet(3). 

Namel The name or address of the gateway to which messages should be for- 

warded. 

Value A metric indicating the hop count to the destination host or network. 

One of the keywords passive, active or external indicates if the gateway should be 
treated as passive or active (as described above), or whether the gateway is external to 
the scope of the routed protocol. 

Internetwork routers that are directly attached to the ARPANET or Milnet should use 
the Exterior Gateway Protocol (EGP) to gather routing information rather then using a 
static routing table of passive gateways. EGP is required in order to provide routes for 
local networks to the rest of the Internet system. Sites needing assistance with such 
configurations should contact the Computer Systems Research Group at Berkeley. 

For a node to run routed, it must be correctly configured to run SysV TCP/IP. See 
Configuring and Managing TCP/IP for more information about routed. 
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NOTES 

The routed daemon is normally started on a node at boot time, from the /etc/rc.loca! 
file. We recommend that you run routed on each gateway to dynamically update the 
gateway’s routing tables. You can also run routed on hosts so they receive the latest 
routing information. 

FILES 

/etc/gatewavs for distant gateways 

BUGS 

The kernel’s routing tables may not correspond to those of routed when redirects 
change or add routes. The only remedy for this is to place the routing process in the 
kernel. 

routed does not incorporate other routing protocols, such as Xerox NS and EGP. Using 
separate processes for each requires configuration options to avoid redundant or com- 
peting routes. 

routed does not currently listen to intelligent interfaces, such as an IMP, and to error 
protocols, such as ICMP, to gather more infonnation. It does not always detect uni- 
directional failures in network interfaces (e.g., when the output side fails). 

SEE ALSO 

udp(7), htable(lM), route(lM), rc(lM); 

Configuring and Managing TCP! IP-, 

“Internet Transport Protocols”, XSIS 028112, Xerox System Integration Standard. 
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NAME 

rshd - remote shell server 

SYNOPSIS 

/etc/rshd 

DESCRIPTION 

rshd is the server for the remd(3) routine and, consequently, for the rsh(lC) program. 
The server provides remote execution facilities with authentication based on privileged 
port numbers from trusted hosts. 

rshd listens for service requests at the port indicated in the “cmd” service 
specification; see services(4). When a service request is received the following proto- 
col is initiated: 

1) The server checks the client’s source port. If the port is not in the range 0- 
1023, the server aborts the connection. 

2) The server reads characters from the socket up to a null (‘NO’) byte. The resul- 
tant string is interpreted as an ASCII number, base 10. 

3) If the number received in step l is non-zero, it is interpreted as the port number 
of a secondary stream to be used for the stderr. A second connection is then 
created to the specified port on the client’s machine. The source port of this 
second connection is also in the range 0-1023. 

4) The server checks the client’s source address and requests the corresponding 
host name (see gethostbyaddr(3N), hosts(4) and named(lM)). If the host- 
name cannot be determined, the dot-notation representation of the host address 
is used. 

5) A null terminated user name of at most 16 characters is retrieved on the initial 
socket. This user name is interpreted as the user identity on the client ’s 
machine. 

6) A null terminated user name of at most 16 characters is retrieved on the initial 
socket. This user name is interpreted as a user identity to use on the server ’s 
machine. 

7) A null terminated command to be passed to a shell is retrieved on the initial 
socket. The length of the command is limited by the upper bound on the size 
of the system’s argument list. 

8) rshd then validates the user according to the following steps. The local 
(server-end) user name is looked up in the password file and a chdir is per- 
formed to the user’s home directory. If either the lookup or chdir fail, the 
connection is terminated. If the user is not the super-user, (user id 0), the file 
/etc/hosts.equiv is consulted for a list of hosts considered ‘ ‘equivalent”. If the 
client’s host name is present in this file, the authentication is considered suc- 
cessful. If the lookup fails, or the user is the super-user, then the file .rhosts in 
the home directory of the remote user is checked for the machine name and 
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identity of the user on the client’s machine. If this lookup fails, the connection 
is terminated. 

9) A null byte is returned on the initial socket and the command line is passed to 
the normal login shell of the user. The shell inherits the network connections 
established by rshd. 

DIAGNOSTICS 

Except for the last one listed below, all diagnostic messages are returned on the initial 
socket, after which any network connections are closed. An error is indicated by a lead- 
ing byte with a value of 1 (0 is returned in step 9 above upon successful completion of 
all the steps prior to the execution of the login shell). 

locuser too long 

The name of the user on the client’s machine is longer than 16 charac- 
ters. 

remuser too long 

The name of the user on the remote machine is longer than 16 charac- 
ters. 

command too long 

The command line passed exceeds the size of the argument list (as 
configured into the system). 

Login incorrect . 

No password file entry for the user name existed. 

No remote directory. 

The chdir command to the home directory failed. 

Permission denied. 

The authentication procedure described above failed. 

Can't make pipe. 

The pipe needed for the stderr, wasn’t created. 

Try again. 

A fork by the server failed. 

<shellname>: . . . 

The user’s login shell could not be started. This message is returned on 
the connection associated with the stderr, and is not preceded by a flag 
byte. 
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BUGS 

The authentication procedure used here assumes the integrity of each client machine 
and the connecting medium. This is insecure, but is useful in an “open” environment. 

SEE ALSO 

rsh(lC), rcmd(3X); 

Configuring and Managing TCP/IP. 



Commands 



9-153 




RTCHK(IM) 



Domain/OS SysV 



RTCHK(IM) 



NAME 

rtchk — test traffic between adjacent routers 

SYNOPSIS 

/etc/rtchk [ options ] 

DESCRIPTION 

rtchk performs a simple test to verify that the router is able to pass packets to and from 
an adjacent router, rtchk is for use in a Domain internet. 

Use the -device option to specify a network controller to test. You must give a device 
type (for example, RING, IIC) to the device option. The rtsvc program, with no 
command-line options, shows you which network devices your node has. 

Older versions of rtchk used a different command-line syntax to specify the type of 
network hardware checked. The old command-line options still work in rtchk version 
10.1, but are no longer supported. 

For more information on rtchk, see Managing Domain Routing and Domain/OS in an 

Internet. 

OPTIONS 

— n net. node id Test packet transmission to and from the specified node. The net- 
work id net must be a network that the router touches. If you use 
— n without —dev, you must specify a net. node id. If you use — n 
with —dev, you must specify only the nodejd, without the net- 
work number. 

— dev[ice] dev-name [dev-num] 

Test packet transmission over a specific network device. Use the 
rtsvc program to display the names (used for dev-name) and con- 
troller numbers (used for dev-num) of the network devices 
attached to your node. 

If you do not also specify a — n option, rtchk broadcasts its test 
packets. If the network contains more than one other node, rtchk 
receives more responses to its test packets than expected and 
prints warning messages. If you specify a -n option with the 
—dev option, rtchk sends the test packets only to the node you 
specify. 

Specify the number of test packets to exchange with the other 
router. If-s is not specified, 10 packets are exchanged. 

Specify that each test packet carries 1024 bytes of test data. 

Omit test data from the test packets. 



-s n 

— dat (default) 
-nodat 
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EXAMPLES 

Exchange 1000 test packets with node 4851 on network 3CE02A8. The router must be 
attached to that network. 

$ /etc/rtchk -n 3CE02A8.4851 -s 1000 

Exchange 10 short test packets with the other node attached to the IIC or T1 connec- 
tion. 

$ /etc/rtchk -nodat 

Exchange 100 test packets with the other node on the IIC or T1 network. 

$ /etc/rtchk -dev iic -s 100 

Exchange 10 test packets with node 666 on the ring network. 

$ /etc/rtchk -dev ring -n 666 
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NAME 

rtstat - display internet router information 

SYNOPSIS 

/etc/rtstat [ options ] 

DESCRIPTION 

rtstat shows the behavior of an internet router at each of its network ports, rtstat is 
used in Domain internets. However, it can provide information about non-routing 
nodes as well as routing nodes. 

For more information on rtstat, see Managing Domain Routing and Domain/OS in an 

Internet. 

OPTIONS 

—dev Report device-specific statistics for each port. 

-net [net id ...] 

Report counts of references to each network specified. The reference 
counts for each network are roughly proportional to the number of pack- 
ets transmitted towards the network, but may be somewhat higher, -net 
with no arguments uses the list of visible networks. 

-r [n] Repeat every n seconds. If n is omitted, repeat every 10 seconds. 

-n node spec ... 

Report statistics for each node in the list. 

If this option is omitted, rtstat reports statistics for the local node only. 

-desc[ribe] Print a description, several lines long, of each statistic. The description 
appears only once for each statistic, the first time it is printed with a 
nonzero value. 

EXAMPLES 

1 . $ /etc/rtstat 



3D9 


pkt s routed: 


110024 


queue oflo: 


0 




misrouted : 


0 


rt too far: 


14 


RING 


pkts sent: 


73278 


pkts revd: 


72434 


IIC 


pkts sent: 


67830 


pkts revd: 


61077 
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2 . $ /etc/rtstat -net 



1232 .3D9 



RING 



IIC 



pkts routed: 


110024 


queue oflo: 


0 


misrouted: 


0 


rt too far: 


14 


pkts sent: 


73278 


pkts revd: 


72434 


towards net: 


1232 


ref ent : 


74540 


pkts sent: 


67830 


pkts revd: 


61077 


towards net: 


1234 


ref ent : 


53532 


towards net: 


1231 


ref ent: 


9193 


towards net: 


1233 


ref ent: 


5105 
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NAME 

rtsvc — set or display internet routing service 
SYNOPSIS 

/etc/rtsvc [-device dev-name [ dev-number ] [options]] 

DESCRIPTION 

rtsvc displays or alters the characteristics of a network port, rtsvc is used in Domain 
internets. You must be logged on to the node you wish to control in order to use rtsvc. 

For complete information on rtsvc, see Managing Domain Routing and Domain/OS in 
an Internet. 

OPTIONS 

If no options are specified, rtsvc displays the characteristics of every active network. If 
you specify any other options, you must specify the type of network controller by using 
a —device command-line option. 

You may use only one -device option on any command line: 

-dev[ice dev-name [dev-number] 

Specify the network device type: RING, IIC, or USER (for EtherBridge 
routers). The device number applies only to USER devices. You may use 
the name ETHERBRIDGE in place of USER if you prefer. The dev- 
number option applies only to USER networks, and is required. Find the 
device number by using rtsvc without command line options (as shown 
in the examples). 

Earlier versions of the rtsvc command used a different command-line 
syntax for specifying network devices. The old command lines still 
work, but you should start using the new -device command lines as soon 
as possible. Future versions of rtsvc will not accept the older command 
lines. 

This option changes the network ID of any network port: 

-net net id Assign the port a hexadecimal network ID number. 

Note: If you use this option to change the network ID of a port on an 
active router, other nodes on the network can stop communicating with 
each other. Use this option only as directed in Managing Domain Rout- 
ing and Domain/OS in an Internet. 
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-route 

-noroute 

-off 

-user nn 



You can specify only one of the following options at a time: 

Allow routing service to or from the port. 

Allow normal Domain/OS requests but no routing service. 

Do not allow Domain/OS requests or routing service. 

Set an EtherBridge network. The value is not changed until the routing 
node is rebooted or the routing process is stopped and restarted. 



EXAMPLES 

$ /etc/rtsvc -device iic -net 007302ED -route 



Assign a network ID to the Interphase controller and allow internet routing at that port. 

$ /etc/rtsvc -dev ring -noroute 

Stop internet routing through the ring port, but allow normal Domain/OS is requests for 
paging, file service, etc. Do not change the node’s network ID: 

$ /etc/rtsvc 



Display the networks attached to this node. 



Controller Net ID Service offered 



RING 7 6A0 Own traffic only 

USER 46 768C Port not open 

The node in the last example touches two networks: a Domain ring and an ETHER- 
NET, via the EtherBridge product. You need the device number information ("46") 
from this display in order to turn on routing at the EtherBridge network. Use the device 
number as shown here: 

$ /etc/rtsvc —dev user 46 -route 

"46" is the device number. 



Commands 



9-159 




RWHOD(IM) 



SysV 



RWHOD(IM) 



NAME 

rwhod - system status server 

SYNOPSIS 

/etc/rwhod [ — w ] 

DESCRIPTION 

The rwhod server maintains the database used by the rwho(lC) and ruptime(lC) pro- 
grams. Its operation is predicated on the ability to broadcast messages on a network. 

On Apollo networks, rwhod has been changed to take advantage of the Domain distri- 
buted file system and to reduce contention for the rwho directory. Since on Apollo net- 
works, there is no need for every host on the network to maintain its own 
/usr/spool/rwho directory, a change has been made to allow you to specify one host per 
network who will write the information to a master /usr/spool/rwho directory. All the 
other hosts link to that master directory to access the information but do not write to the 
directory. Specifically, rwhod writes to /usr/spool/rwho only if that directory is local 
to the node, or if the optional — w switch is supplied. 

rwhod both produces and consumes system status information. It periodically queries 
the state of the system and constructs status messages which are broadcast on a net- 
work, and it listens for other rw hod servers’ status messages as well. When it receives 
a status message from another server, rwhod validates it and records it in a file located 
in the directory /usr/spool/rwho, if the directory is physically located on the host or if 
rwhod was started with the — w switch. On hosts where rwhod was started without the 
— w switch and where /usr/spool/rw ho is a link to a remote host, rwhod does not write 
to the directory. 

The rwho server transmits and receives messages at the port indicated in the “rwho” 
service specification. The messages sent and received, are of the form: 

struct outmp { 

char out_line[8];/* tty name */ 
char out_name[8];/* user id */ 
long out_time;/* time on */ 

}; 

struct whod { 

char wd_vers; 

char wd_type; 

char wd_fill[2]; 

int wd_sendtime; 

int wd_recvtime; 

char wd_hostname[32]; 
int wd_loadav[3]; 

int wd_boottime; 

struct whoent { 

struct outmp we_utmp; 
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int we_idle; 

} wd_we[1024 / sizeof (struct whoent)]; 

}; 

All fields are converted to network byte order before transmission. The load averages 
represent averages over the 5, 10, and 15 minute intervals prior to a server’s transmis- 
sion. The host name included is that returned by the gethostname(2) system call. The 
array at the end of the message contains information about the users logged in to the 
sending machine. This information includes an entry for each non-idle terminal line 
and a value indicating the time since a character was last received on the terminal line. 

Messages received by the rwho server are discarded unless they originated at an rwho 
server’s port. In addition, if the host’s name, as specified in the message, contains any 
unprintable ASCII characters, the message is discarded. Valid messages received by 
rwhod are placed in files named whod. hostname in the directory /usr/spool/rwho. 
These files contain only the most recent message, in the format described above. 

OPTIONS 

— w Update the files in the /usr/spool/rwho directory, even if the directory is 

not local to the node. 



NOTES 

Note that rwhod will update the files in the /usr/spool/rwho directory in two cases: 

1. If the /usr/spool/rwho directory is physically located 
on that host. 

2. If rw hod was started with the — w switch. 

To reduce contention for the rwho directory and provide updated information to hosts, 

we recommend that you 

o Physically locate the /usr/spool/rwho directory on the network’s TCP/IP adminis- 
trative node. All other hosts on the network should be set up so that 
/usr/spool/rwho is a link to the administrative node. 

o If you are running rw hod in a Domain internet, you can configure your network in 
one of two ways: 

1. Configure one node on each subnet to have a local /usr/spool/rwho 
and link all other nodes on that subnet to that node. 

2. Configure all nodes in the internet to link to one master TCP/IP 
administrative node containing the /usr/spool/rwho directory. 

This enables the rwho and ruptime utilities to see all nodes in the 
internet. 
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In order to make this arrangement work, you must run rwhod — w on one 
node on each subnet. They will then write their subnet’s information 
to the directory on the internet’s master TCP/IP administrative node. 

You also can run rwhod on a gateway to see broadcasts from two 
networks. 

rwhod, like other SysV daemons, is invoked at boot time by the /etc/rc.local startup 
file. See Configuring and Managing TCP IIP for more information about rwhod. 

NOTES 

People often interpret the server’s dying as a machine in the network going down. 

SEE ALSO 

rwho(lC), ruptime(lC), rc(lM), 
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NAME 

sa, accton - system accounting 
SYNOPSIS 

/etc/sa [ -abcdDfijkKInrstuv ] [ — S savacctfile ] [ -U usracctfile ] [file ] 
/etc/accton [ file ] 

DESCRIPTION 

When you specify an argument naming an existing file, action causes system account- 
ing infonnation for every process executed to be placed at the end of the file. If no 
argument is given, accounting is turned off. 

The sa command reports on, cleans up, and generally maintains accounting files. 

sa is able to condense the information in /usr/adm/acct into a summary file 
/usr/adm/savacct, which contains a count of the number of times each command was 
called and the time resources consumed. This condensation is desirable because on a 
large system /usr/adm/acct can grow by 100 blocks per day. The summary file is nor- 
mally read before the accounting file, so the reports include all available information. 

If a filename is given as the last argument, that file is treated as the accounting file; 
/usr/adm/acct is the default. 

Output fields are labeled: “cpu” for the sum of user+system time (in minutes), “re” 
for real tune (also in minutes), “k” for cpu-time averaged core usage (in Ik units), 
“avio” for average number of I/O operations per execution. With options fields 
labeled “tio” for total I/O operations, “k*sec” for cpu-storage integral (kilo-core 
seconds), “u” and “s” for user and system cpu-time alone (both in minutes) will 
sometimes appear. 



OPTIONS 




-a 


Prints all command names, even those containing unprintable characters 
and those used only once. By default, those are placed under the name 
‘***other.’ 


-b 


Sorts output by sum of user and system time divided by number of calls. 
The default sort is by sum of user and system times. 


— c 


Prints percentage of total time over all commands, in addition to total 
user, system, and real time for each command. 


-d 


Sorts by average number of disk I/O operations. 


-D 


Prints and sorts by total number of disk I/O operations. 


-f 


Forces no interactive threshold compression with — v flag. 


-i 


Does not read in summary file. 


-j 


Givse seconds per call, instead of total minutes time for each category. 


-k 


Sorts by cpu-time average memory usage. 
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— K Prints and sort by cpu-storage integral. 

-I Separates system and user time; normally they are combined. 

-m Prints number of processes and number of CPU minutes for each user. 

-n Sorts by number of calls. 

-r Reverses order of sort. 

— s Merges accounting file into summary file /usr/adm/savacct when done. 

-t Reports ratio of real time to sum of user and system times for each com- 

mand. 

-u Prints user ID and command name for each command in the accounting 

file, superseding all other flags. 

—xn Followed by a number n, types the name of each command used n times 

or fewer. Awaits a reply from the terminal; if it begins with ‘y’, adds the 

command to the category ‘**junk**.’ This is used to strip out garbage. 

— S savacctfile The file savacctfile becomes the command summary file instead of 
/usr/adm/savacct. 

— U usrac'ctfile 

The file usracctfile becomes the per-user statistics file instead of 
/usr/adm/usracct to accumulate the -m option output. 

FILES 

/usr/adm/acct Raw accounting 

/usr/adm/savacct Summary 

/usr/adm/usracct Per-user summary 

NOTES 

Domain/OS systems report half the process time as user time, and half as system time. 
Add these two to obtain the overall process CPU time when using the -I option. 

The /usr/adm directory is usually a link to ‘node_data/adm. This allows you to have a 
separate accounting file for each node, if you run accounting on diskless nodes. 

SEE ALSO 

acct(2) 
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NAME 

salad - salvage an access control list 
SYNOPSIS 

/etc/salad [options] [volume] 

DESCRIPTION 

salad salvages the (Access Control List (ACL) structure on the volume you specify. It 
merges duplicate ACLs into a single copy, and deletes unused ACLs. You should run 
salad once a week or so unless you never receive reports that reference counts need 
repairing (that is, everything is perfect). 

salad cannot merge duplicate ACLs on files that are currently in use (locked) (for 
example, library files). This is not especially serious, as the duplication consumes very 
little disk space. To merge all possible ACLs on a node, including things like libraries, 
bring the node up diskless, mount the volume using mtvol, and then ran salad on the 
mounted volume. 

volume (optional) Specify the entry directory pathname for the volume whose acls 
you intend to salvage. Note that salad cannot salvage a volume 
mounted on a remote node. 



OPTIONS 

-n[o_]s[unimary] 

— v[erifv] 

-n[o_]m[erge] 

— I[ist] 

-u 



Default if omitted: "/" node entry directory 

Suppress summary information. 

Verify only; do not delete or merge any ACLs. 

Do not merge duplicate ACLs into a single copy. 

List the UIDs of the ACLs that are being combined. 

This option causes salvol to scan for files and directories with 
ACLs. When it encounters one, it puts out a line with UID of the 
ACL, followed by the UID of the file or directory. It also indi- 
cates the type of ACL, whether file or directory, and whether ini- 
tial or not. 



EXAMPLES 

$ /etc/salacl 

Warning: unable to merge two equivalent ACLs : 
// grover/sys/node_data/boot_shell — 
object is in use (OS/file server) 
acl objects found: 24 

acls merged with equivalents: 12 
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Salvage the ACLs of the current volume. 

$ /etc/salad -v 

acl objects found: 24 

acls which could be merged: 12 

$ /etc/salad -1 

3A39A9F3 . 4000CBD6 39A77EF0 . 4000CBD6 (equiv acl) 
3A75D6C2 .E000CBD6 39A77EF0 . 4000CBD6 (equiv acl) 
3AEE67CA. 7000CBD6 39A77EF0 . 4000CBD6 (equiv acl) 
3AEF69EE .EOOOCBD6 39A77EF0 . 4000CBD6 (equiv acl) 
3AEFA618 . 7000CBD6 382E6E87 . A000CBD6 (equiv acl) 
ACL objects found: 43 

5 



(dir) 

(dir) 

(file) 

(dir) 

(dir def) 
(file def) 






ACLs merged with equivalents: 



$ /etc/salad -v -u 

3AE41FE2 .D000CBD6 393D4261 .B000CBD6 
3AE41F4B. 5000CBD6 380A147 9 . 1000CBD6 
3A39A9F3 . 4000CBD6 3A39A9F2 . 3000CBD6 
3AE41F85 . 0000CBD6 380A1472 .F000CBD6 
3AE41F84 .F000CBD6 380A1472 . F000CBD6 
3AE41F81 .E000CBD6 380A1472 . F000CBD6 
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NAME 

salvol - verify and correct allocation of disk blocks 
SYNOPSIS 

/etc/salvol [options] [ Ivjmm ] (from shell) 
ex salvol (from mnemonic debugger) 

DESCRIPTION 

Each logical volume is divided into disk blocks, salvol verifies and, if necessary, 
corrects the tables that describe the allocation of disk blocks to the files stored on the 
disk, salvol also returns to the free space pool all blocks that are no longer in use: those 
allocated to temporary files or to deleted portions of permanent files. 

salvol can usually restore a disk after a system crash or an improper unmounting of a 
volume. 



If no options are specified on the command line, then salvol prompts for all required 
arguments and options. 

Ivjmm (optional) 

A decimal value for which logical volume number to salvage. 



OPTIONS 

—a Read all blocks in all files. This option will take longer to run and is 

useful for finding block header errors or file blocks that cannot be read. 
This option is not useful for finding multiply allocated blocks or general 
disk problems. 



-c c[cnum:[d_num] 

controller type: 

c = { w, s, f} (for winchester, storage module or floppy) 
cnum - controller number, if specified, must be followed by a 
d num = drive number 



This flag must be specified if any command-line options are used. 

-f Fix error without prompting. (The default is to prompt.) 

-h Print help text. 

-n Check disk; only salvage if disk needs salvaging. This option is useful 

in scripts that mount secondary disks at boot tune. 

— p Polite mode; pause before overflowing screen. (The default is offline.) 

— s Show some file statistics at completion. 

— t Terminal mode, do not pause during output. (The default is online.) 

— v Verify only; do not write anything to disk. 
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NAME 

sendmail - send mail over the internet 
SYNOPSIS 

/usr/lib/sendmail [ flags ] [ address ... ] 

newaliases 

mailq [ — v ] 

DESCRIPTION 

sendmail sends a message to one or more recipients, routing the message over whatever 
networks are necessary, sendmail does internetwork forwarding as necessary to deliver 
the message to the correct place. 

sendmail is not a user interface routine; other programs provide simpler front ends, 
sendmail is used only to deliver pre-formatted messages. 

With no flags, sendmail reads its standard input up to an end-of-file, or to a line consist- 
ing of a single dot, and sends a copy of the message found there to all of the addresses 
listed. It determines the network(s) to use based on the syntax and contents of the 
addresses. 

Local addresses are looked up in a file and aliased appropriately. Aliasing can be 
prevented by preceding the address with a backslash. Normally, the sender is not 
included in any alias expansions. For example, if “john” sends to “group” and 
“group” includes “john” in the expansion, then the letter will not be delivered to 
“john”. 

In aliases, the first character of a name may be a vertical bar, to cause sendmail to 
interpret the rest of the name as a command to pipe the mail to. It may be necessary to 
quote the name to keep sendmail from suppressing the blanks between arguments. 
Aliases may also have the syntax ‘“include: filename ” to ask sendmail to read the 
named file for a list of recipients (see EXAMPLES, below). 

FLAGS 

— ba Go into ARPANET mode. All input lines must end with a CR-LF, and all 

messages will be generated with a CR-LF at the end. Also, the “From:” 
and “Sender:” fields are examined for the name of the sender. 

— bd Run as a daemon. This requires Berkeley IPC. sendmail will fork and 

run in background, listening on socket 25 for incoming SMTP connec- 
tions. This is normally run from /etc/rc. 

— bi Initialize the alias database. 

— bm Deliver mail in the usual way (default). 

—bp Print a listing of the queue. 
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-bs Use the SMTP protocol as described in RFC821 on standard input and 

output. This flag implies all the operations of the -ba flag that are com- 
patible with SMTP. 

-bt Run in address test mode. This mode reads addresses and shows the 

steps in parsing; it is used for debugging configuration tables. 

-bv Verify names only - do not try to collect or deliver a message. Verify 

mode is normally used for validating users or mailing lists. 

-bz Create the configuration freeze file.. Domain/OS SysV doesn’t support 

frozen configuration files. 

— C file Use alternate configuration file, sendmail refuses to run as root if an 

alternate configuration is specified. The frozen configuration file is 
bypassed. 

-dX Set debugging value to X. 

-Ffullname Set the full name of the sender. 

— f name Set the name of the “from” person (i.e., the sender of the mail). — f can 

only be used by “trusted” users (normally root, daemon, and network), 
or if name is the same as your log-in name. 

-hV Set the hop count to N. The hop count is incremented every time the mail 

is processed. When it reaches a limit, the mail is returned with an error 
message, the victim of an aliasing loop. If not specified, “Received:” 
lines in the message are counted. 

-n Don’t perform aliasing. 

-ox value Set option x to the specified value. Options are described below. 

-q [time] Processed saved messages in the queue at time intervals. If time is omit- 

ted, process the queue once. Time is given as a tagged number, with 
“s” being seconds, “m” being minutes, “h” being hours, “d” being 
days, and “w” being weeks. For example, “— qlh30m” or “-q90m” 
would both set the interval between processing passes to one hour thirty 
minutes. If time is specified, sendmail will run in background. The 
option can be used safely with — bd. 

-r name An alternate (obsolete) form of the — f flag. 

-1 Read message for recipients. To:, Cc:, and Bcc: lines will be scanned 

for recipient addresses. The Bcc: line will be deleted before transmis- 
sion. Any addresses in the argument list will be suppressed; that is, they 
will not receive copies even if listed in the message header. 

— v Go into verbose mode. Alias expansions will be announced, etc. 
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OPTIONS 

A number of processing options may be set. Normally, a system administrator will set 
these. Options may be invoked either on the command line using the — o flag or in the 
configuration file. The options are: 



Afile 

c 

dr 



D 

ex 



F mode 

f 

H file 



L n 

m 

o 



Use an alternate alias file. 

Queue messages, rather than connecting immediately to mailers that are 
considered “expensive”. 

Set the delivery mode to x. Delivery modes are “i” for interactive (syn- 
chronous) delivery, “b” for background (asynchronous) delivery, and 
“q” for queue only - that is, actual delivery is made the next time the 
queue is run. 

Try to automatically rebuild the alias database, if necessary. 

Set error processing to mode x. Valid modes are “m” to mail back the 
error message, “w” to “write” back the error message (or mail it back 
if the sender is not logged in), “p” to print the errors on the terminal 
(default), “q” to throw away error messages (only exit status is 
returned), and “e” to do special processing for the BerkNet. If the text 
of the message is not mailed back by modes “m” or “w” and if the 
sender is local (this machine), a copy of the message is appended to the 
file “dead.letter” in the sender’s home directory. 

Cause sendmail to use this mode when creating temporary files. (See 
chmod(l)). 

Save UNIX From lines at the front of messages. 

Use N as the default group ID when calling mailers. 

Call the SMTP help file. 

Ignore a dot on a line by itself as a message temiinator. 

Set the log level. 

Send to “me” (the sender) also, if I am in an alias expansion. 

Use old style headers, if possible. If not set, this message is guaranteed 
to have new style headers (i.e., commas instead of spaces between 
addresses). If set, an adaptive algorithm is used that will correctly deter- 
mine the header format in most cases. 



Q queuedir Select the directory in which to queue messages. 

r timeout Set the timeout on reads. If none is set, sendmail will wait indefinitely 

for a mailer. This option violates the word (if not the intent) of the 
SMTP specification; show the timeout should probably be fairly large. 

Sfile Save statistics in the named file. 
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s Restart the queue file, even under circumstances where it is not strictly 

necessary. This provides safety against system crashes during delivery. 

T time Set the timeout on undelivered messages in the queue to the specified 

time. After delivery has failed (for example, because of a host being 
down) for this amount of time, failed messages will be returned to the 
sender. The default is three days. 

t stz,dtz Set the name of the time zone. Stz is standard time zone; dtz is daylight 

time zone. 

il N Set the default user ID for mailers to N. 

sendmail returns an exit status describing what it did. The codes are defined in 
< sysexits.h > 

EX_OK Successful completion on all addresses. 

EX_NOUSER Username not recognized. 

EX_UNAVAILABLE Catchall meaning necessary resources were not available. 
EX_SYNTAX Syntax error in address. 

EX_SOFTWARE Internal software error, including bad arguments. 

EX_OSERR Temporary operating system error, such as “cannot 

fork”. 

EX_NOHOST Host name not recognized. 

EX_TEMPFAIL Message could not be sent immediately, but was queued. 

If invoked as newaliases, sendmail will rebuild the alias database. If invoked as 
mailq, sendmail will print the contents of the mail queue. 

EXAMPLES 

The following alias pipes sendmail to the msgs(l) command: 
msgs: "|/usi7ucb/msgs -s" 

An alias such as: 

poets: " :include:/usi7local/lib/poets.list" 
would read /usr/local/lib/poets.list for the list of addresses making up the group. 

NOTES TO SysV USERS 

If you are running sendmail as a daemon, you must run newaliases on the same node 
that is running the sendmail daemon. Once newaliases has completed, you must kill 
and restart the sendmail daemon for the changes to take effect. 

FILES 

Except for /usr/lib/sendmail.cf, these pathnames are all specified in 
/usr/lib/sendmail.cf. Thus, these values are only approximations. 

/usr/lib/aliases raw data for alias names, in text 

/usr/lib/aliases.pag database of alias names used by sendmail 

/usr/lib/aliases.dir database of alias names used by sendmail 
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/usr/lib/sendmail.cf 
/usr/li b/uucp proto.cf 
/usr/1 i b/a r pa p roto.cf 
/usr/Iib/sendmail.st 
/usr/bin/uux 
/usr/spool/mqueue/* 
/usr/lib/sendmail.hf 
/usr/lib/sendmail.fc 



configuration file 

example uucp configuration file 

example ARPANET configuration file 

collected statistics 

to deliver uucp mail 

temp files 

help files 

frozen configuration 



SEE ALSO 

binmail(l), mail(l), syslog(3), aliases(4), sendmail.cf(4), mailaddr(5), rc(lM); 
DARPA Internet Request For Comments RFC819, RFC821, RFC822; 

Using Your SysV Environment. 
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NAME 

server - run a server process 
SYNOPSIS 

/etc/server [-p] "command-pathname argl arg2 ..." 

DESCRIPTION 

The server command runs a program with an identity of user "user" and group "server" 
just as if the command had been started using the Display Manager’s cps command. It 
also marks the new process in such a way that the server program will not be terminated 
by the Display Manager when the user logs out. 

In addition to allowing users to start server processes, this command is useful for killing 
servers that are running with the identity user.server. For example, 

$ /etc/server /bin/kill -9 1532 
OPTIONS 

— p The -p option preserves the current SID of the person issuing the com- 

mand. Otherwise, /etc/server sets the SID to user.server.none for the 
command. 

SEE ALSO 

init(lM), rc(lM) 
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NAME 

setmnt — establish mount table 

SYNOPSIS 

/etc/setmnt 

DESCRIPTION 

setmnt creates the /etc/mnttab table needed for both the mount (1M) and umount 
commands, setmnt reads standard input and creates a mnttab entry for each line. 
Input lines have the format: 
filesys node 

where: filesys is the name of the file system’s "special file" (e.g., /dev/dsk/c?d?s?) 
and node is the root name of that file system. Thus filesys and node become the first 
two strings in the mount table entry. 

FILES 

/etc/mnttab 

SEE ALSO 

mount(lM) 

BUGS 

Problems may occur if filesys or node are longer than 32 characters. 

setmnt silently enforces an upper limit on the maximum number of mnttab entries. 
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NAME 

shovv_lc — shell script to indicate obsoleted system calls in a binary file 
SYNOPSIS 

/etc/show_lc binary Jile ... 

DESCRIPTION 

This script will show which calls in an object module have been obsoleted and replaced. 
This will not show which procedure made the call. Generate an xref listing to do that. 
Nor will it show any use of the old name_$name_t or name_$pname_t data types. 
You must ensure that the object being examined is in fact an object module. 

The binary Jile argument is required. 

SEE ALSO 

run(l) 
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NAME 

shutdown - shut down system, change system state 

SYNOPSIS 

/etc/shutdown [ — y ] [ -g grace _period [ —\init_state ] 

DESCRIPTION 

This command is executed by the super-user to change the state of the machine. By 
default, it brings the system to a state where only the console has access to the UNIX 
system. This state is traditionally called "single-user". 

The command sends a warning message and a final message before it starts shutdown 
activities. By default, the command asks for confirmation before it starts shutting down 
servers and killing processes. 

OPTIONS 

-v Pre-answers the confirmation question so that the command can be run 

without user intervention. A default of 60 seconds is allowed between 
the warning message and the final message. Another 60 seconds is 
allowed between the final message and the confirmation. 

-g grace _period 

Allows the super-user to change the number of seconds from the 60- 
second default. 

-i i nit _s tare Specifies the state that init(lM) is to be put in following the warnings, if 

any. By default, system state "s" is used (the same as states "1" and "S"). 

Recommended system state definitions: 

State 0 Shut the machine down so it is safe to remove the power. Have the 

machine remove power if it can. The /etc/re() procedure is called to do 
this work. 

State l , s, S Bring the machine to the state traditionally called single-user. The 
/etc/rcO procedure is called to do this work. (Though s and I are both 
used to go to single user state, s only kills processes spawned by init and 
does not unmount file systems. State I unmounts everything except root 
and kills all user processes, except those that relate to the console.) 

State 5 Stop the UNIX system and go to the firmware monitor. 

State 6 Stop the UNIX system and reboot to the state defined by the initdefault 

entry in /etc/initlab. 

SEE ALSO 

init(lM), rcO(lM), rc2(lM). 
inittab(4) 
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NAME 

st race - print STREAMS trace messages 
SYNOPSIS 

/etc/strace [ mid sid level ] ... 

DESCRIPTION 

strace without arguments writes all STREAMS event-trace messages from all drivers 
and modules to its standard output. These messages are obtained from the STREAMS 
log driver (log(7)). If arguments are provided they must be in triplets of the form mid 
sid level, where mid is a STREAMS module id number, sid is a sub-id number, and level 
is a tracing priority level. Each triplet indicates that tracing messages are to be received 
from the given module/driver, sub-id (usually indicating minor device), and priority 
level equal to or less than the given level. The token all may be used for any member 
to indicate no restriction for that attribute. 

The format of each trace message output is 

<seq> <time> <ticks> <level> <flags> <mid> <sid> <text> 



<seq> 


Trace-sequence number 


<time> 


Time of message in hh:mm:ss 


<ticks> 


Time of message in machine ticks since boot 


<level> 


Tracing priority level 


<flags> 


E : message is also in the error log 
F : indicates a fatal error 

N : mail was sent to the system administrator (not applicable) 


<mid> 


Module id number of source 


<sid> 


Sub-id number of source 


<text> 


Formatted text of the trace message 



Once initiated, strace continues to execute until terminated by the user. 

EXAMPLES 

Output all trace messages from the module or driver whose module id is 41: 
strace 41 all all 

Output those trace messages from driver/module id 41 with sub-ids 0, 1, or 2: 
strace 410 I 41 1 1 41 2 0 

Messages from sub-ids 0 and 1 must have a tracing level less than or equal to 1. Those 
from sub-id 2 must have a tracing level of 0. 

CAVEATS 

Due to performance considerations, only one strace process is permitted to open the 
STREAMS log driver at a time. The log driver has a list of the triplets specified in the 
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command invocation, and compares each potential trace message against this list to 
decide if it should be fonnatted and sent up to the strace process. Hence, long lists of 
triplets have a greater impact on overall STREAMS performance. Running strace has 
the most impact on the timing of the modules and drivers generating the trace messages 
that are sent to the strace process. If trace messages are generated faster than the 
strace process can handle them, some messages are lost. This last case can be deter- 
mined by examining the sequence numbers on the trace messages output. 

SEE ALSO 

log(7) 

Programming with SysV STREAMS 
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NAME 

strclean - STREAMS error logger clean-up program 
SYNOPSIS 

/etc/strclean [ -d logdir ] [-a age ] 

DESCRIPTION 

strclean is used to clean up the STREAMS error logger directory on a regular basis (for 
example, by using cron(lM)). By default, all files with names matching error.* in 
/usr/adm/streams that were not modified in the last three days are removed. 

OPTIONS 

-d Specifies a directory other than 

/usr/adm/streams. 

—a Changes the maximum age in days for a log file. 

EXAMPLE 

strclean -d /usr/adm/streams -a 3 
has the same result as running strclean with no arguments. 

NOTES 

strclean is typically run from cron(lM) on a daily or weekly basis. 

FILES 

/us r/a d m/s t r ea ms/e r ror . * 

SEE ALSO 

cron(lM), strerr(lM). 

Programming with SysV STREAMS 
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NAME 

streamd - STREAMS device interrupt server 
SYNOPSIS 

/sys/vstreams/streamd [— f] 

DESCRIPTION 

The streamd daemon performs read-side processing by monitoring event counts for all 
devices declared by Stream tails. When an event count is advanced, the interrupt 
handler in the appropriate Stream tail is called. The daemon also performs timeout pro- 
cessing. 

OPTIONS 

The -f flag prevents streamd from forking to become a daemon, and is useful for run- 
ning streamd under the control of a debugger. 

SEE ALSO 

Programming with SysV STREAMS 
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NAME 

strerr - STREAMS error logger server 

SYNOPSIS 

/etc/strerr 

DESCRIPTION 

strerr receives error-log messages from the STREAMS log driver (log(7)) and appends 
them to a log file. The error-log files produced reside in the directory 
/usr/adm/streams, and are named error .mm-dd, where mm is the month and dd is the 
day of the messages contained in each log file. 

The format of an error-log message is 

<seq> <time> <ticks> <flags> <mid> <sid> <text> 

<seq> Error sequence number 

<time> Time of message in hh:mm:ss 

<ticks> Time of message in machine ticks since boot priority level 

<flags> T : the message was also sent to a tracing process 
F : indicates a fatal error 

N : send mail to the system administrator (not implemented) 

<mid> Module id number of source 

<sid> Sub-id number of source 

<text> Formatted text of the error message 

Messages that appear in the error log are intended to report exceptional conditions that 
require the attention of the system administrator. Messages that indicate the total failure 
of a STREAMS driver or module have the F flag set. The priority level usually has no 
meaning in the error log but has meaning if the message is also sent to a tracer process. 

Once initiated, strerr continues to execute until terminated by the user. Commonly, 
strerr is executed asynchronously. 

CAVEATS 

Only one strerr process at a tune is permitted to open the STREAMS log driver. 

If a module or driver is generating a large number of error messages, running the error 
logger causes a degradation in STREAMS performance. If a large burst of messages is 
generated in a short time, the log driver may not be able to deliver some of the mes- 
sages. This situation is indicated by gaps in the sequence numbering of the messages in 
the log files. 
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FILES 

/usr/adrn/strearns/error./wn-<&/ 

SEE ALSO 

log (7) 

Programming with SysV STREAMS 
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NAME 

sync - update the super block 

SYNOPSIS 

sync 

DESCRIPTION 

sync executes the sync system primitive. If the system is to be stopped, sync must be 
called to ensure file-system integrity, sync flushes all previously unwritten system 
buffers out to disk, thus assuring that all file modifications up to that point are saved. 
See sync(2) for details. 

NOTE 

If you have performed a write to a file on a remote machine in a remote file sharing 
environment (RFS), you cannot use sync to force buffers to be written out to disk on the 
remote machine, sync writes only local buffers to local disks. 

SEE ALSO 

sync(2) 
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NAME 

svncids - fix or verify file owners in a file system 
SYNOPSIS 

/etc/syneids [ —a ] [ — 1 ] [ — v ] volume-pathname 
DESCRIPTION 

In a Domain system, every user (and group) is identified by a 64-bit identifier that is 
unique across all Domain users (and groups) in both space and time. However, UNIX 
interfaces that take user and group IDs as arguments expect integers that may be unique 
only within a given file system. The Domain file system stores both forms of identifier 
with each file. The 64-bit UIDs are used for checking access rights, since there can 
never be conflicts even if two networks are merged, or a workstation moves from one 
network to another. 

The integer UNIX IDs are used avoid performing expensive translations for operations 
such as stat(2) and chown(2). 

sv ncids is a program that should be run whenever network registries are merged, or a 
node is moved between networks having different registries. It ensures that the UNIX 
owner IDs match the unique owner IDs for every object on the logical volume. 

OPTIONS 

—a List the name and owner information for each object as it is processed. 

—I Only list information about objects for which UNIX owner IDs are incorrect. 

—v Verify only; do not actually modify the owners of any objects. This option 
implies —I. If the —a option is also given, then information will be printed about 
every object on the volume. 

SEE ALSO 

chown(l), stat(2), fstat(2), chown(2), edrgy(lM). 



9-184 



Commands 




SYSLOGD(IM) 



SysV 



SYSLOGD(IM) 



NAME 

syslogd - log systems messages 
SYNOPSIS 

/etc/syslogd [ — f configfile ] [ -mmarkinterval ] [ -d ] 

DESCRIPTION 

syslogd reads and logs messages into a set of files described by the configuration file 
/etc/svslog.conf. Each message is one line. A message can contain a priority code, 
marked by a number in angle braces at the beginning of the line. Priorities are defined 
in <sys/syslog.h>. syslogd reads from the UNIX domain socket /dev/log, from an 
Internet domain socket specified in /etc/services. 

syslogd configures when it starts up and whenever it receives a hangup signal. Lines in 
the configuration file have a selector to determine the message priorities to which the 
line applies and an action. The action field is separated from the selector by one or 
more tabs. 

Selectors are semicolon separated lists of priority specifiers. Each priority has a facility 
describing the part of the system that generated the message, a dot, and a level indicat- 
ing the severity of the message. Symbolic names may be used. An asterisk selects all 
facilities. All messages of the specified level or higher (greater severity) are selected. 
More than one facility may be selected using commas to separate them. 

For example: 

*.emerg;mail,daemon.crit 

Selects all facilities at the emerg level and the mail and daemon facilities at the crit 
level. 

Known facilities and levels recognized by syslogd are those listed in syslog(3) without 
the leading “LOG_”. The additional facility mark has a message at priority 
LOG_INFO sent to it every 20 minutes (this may be changed with the — m flag). The 
mark facility is not enabled by a facility field containing an asterisk. The level none 
may be used to disable a particular facility. 

For example, 

*.debug;mail.none 

Sends all messages except mail messages to the selected file. 
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The second part of each line describes where the message is to be logged if this line is 
selected. There are four forms: 

• A filename (beginning with a leading slash). The file will be opened in append 
mode. 

• A hostname preceeded by an at sign (@). Selected messages are forwarded to the 
svslogd on the named host. 

• A comma separated list of users. Selected messages are written to those users if 
they are logged in. 

• An asterisk. Selected messages are written to all logged-in users. 

Blank lines and lines beginning with ‘#’ are ignored. 

svslogd creates the file /etc/syslog.pid, if possible, containing a single line with its pro- 
cess id. This can be used to kill or reconfigure svslogd. 

To bring svslogd down, it should be sent a terminate signal (for example, kill cat 
/etc/syslog.pid). 

OPTIONS 

The flags are: 

— f Specify an alternate configuration file. 

—in Select the number of minutes between mark messages. 

— d Turn on debugging. 

EXAMPLE 

The configuration file: 

kern, mark . debug 
* . notice; mail . info 
* . crit 
kern . err 
* . erne rg 
* . alert 

* . alert ; auth . warning 



/dev/ console 

/usr/ spool/ adm/ syslog 

/usr/adm/ critical 

0ucbarpa 

* 

eric, kridle 
ralph 



logs all kernel messages and 20 minute marks onto the system console, all notice (or 
higher) level messages and all mail system messages except debug messages into the 
file /usr/spool/adni/syslog, and all critical messages into /usr/adm/critical; kernel 
messages of error severity or higher are forwarded to ucbarpa. 
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All users will be informed of any emergency messages, the users eric and kridle will 
be informed of any alert messages, and the user ralph will be informed of any alert 
message, or any warning message (or higher) from the authorization system. 

FILES 

/etc/syslog.conf the configuration file 
/etc/syslog.pid the process id 

/dev/log Name of the UNIX domain datagram log socket 

SEE ALSO 

logger(l) 
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NAME 

tcpd - TCP/IP protocol server 
SYNOPSIS 

/etc/tcpd [ -a ] [ -d <mask> ] [ -p <time> ] [ -t <ipttl> ] [ -\\<window> ] 
DESCRIPTION 

Invoking tcpd, the TCP/IP protocol server or daemon, enables a node’s TCP/IP socket- 
call interface and initializes several internal tables required for operation of the proto- 
cols. The tcpd daemon must be mn on every node that uses TCP/IP. Normally, tcpd is 
invoked by the node’s startup file, /etc/rc. 

Options available with this command allow you to define certain parameters of the pro- 
tocols. 



OPTIONS 

-a 



— p <time> 



— t <ipttl> 
—\\<window> 



Suppress delayed packet acknowledgements (ACKs), the default con- 
dition. Delayed ACKs is a performance optimization feature for TCP 
which allows a receiver to delay until 33% of the maximum window 
size offered can be uncovered (but in no case to wait longer than 0.25 
seconds) before it acknowledges received packets. 

Set gateway ping interval in seconds. The value must be expressed in 
HEX and can range from 0 to A. Default value is 4 seconds. Setting 
the interval to 0 inhibits pinging. TCP issues an ICMP Echo Request 
(ping) to local hosts and gateways at the specified interval to verify 
their continued operation. Any gateway that fails to respond after 
three tries is moved to the end of the node’s routing table. 

Set the IP parameter, packet maximum time to live. The value must 
be expressed in HEX and can range from 1 to FF. Default value is IE. 

Set the receive window size (a TCP flow control parameter) in octets. 
The value must be expressed in HEX and can range from 1 to 239C. 
Default value is 239C. 



— d <mask> Display debugging information as defined by the 16-bit mask. See 

the table below for a description of the debug information that can be 
requested. Add bit values to request several types of information. 
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{_Bit Value_} 


{_Debug Information } 


0001 (default) 


General information 


0002 


IP level information 


0004 


ARP information 


0008 


TCP information 


0010 


Data in TCP packets 


0020 


UDP information 


0200 


Broadcasts 


1000 


TCP finite state machine information 


2000 


Device level information 


4000 


Additional detail at any level 


foff 


All available debug information except broadcasts 



SEE ALSO 

netstat( 1 ), ping( lm); 

Configuring and Managing TCP! IP. 
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NAME 

telnetd — DARPA TELNET protocol server 

SYNOPSIS 

/etc/telnetd 

DESCRIPTION 

telnetd is a server which supports the DARPA standard TELNET virtual terminal pro- 
tocol. telnetd is invoked by the internet server (see inetd(lM)), normally for requests 
to connect to the TELNET port as indicated by the /etc/services file (see services(4)). 

telnetd operates by allocating a pseudoterminal device (see pty(7)) for a client, then 
creating a login process which has the slave side of the pseudoterminal as stdin, stdout, 
and stderr. telnetd manipulates the master side of the pseudoterminal, implementing 
the TELNET protocol and passing characters between the remote client and the login 
process. 

When a TELNET session is started up, telnetd sends TELNET options to the client 
side indicating a willingness to do remote echo of characters, to suppress go ahead, and 
to receive terminal type information from the remote client. If the remote client is wil- 
ling, the remote terminal type is propagated in the environment of the created login pro- 
cess. The pseudoterminal allocated to the client is configured to operate in “cooked” 
mode, and with XTABS and CRMOD enabled (see tty(7)). 

telnetd is willing to do: echo, binary , suppress go ahead, and timing mark, telnetd is 
willing to have the remote client do: binary, terminal type , and suppress go ahead. 

BUGS 

Some TELNET commands are only partially implemented. 

The TELNET protocol allows for the exchange of the number of lines and columns on 
the user’s terminal, but telnetd doesn’t make use of them. 

Because of bugs in the original 4.2BSD telnet, telnetd performs some dubious protocol 
exchanges to try to discover if the remote client is, in fact, a 4.2BSD telnet. 

Binary mode has no common interpretation except between similar operating systems 
(the UNIX system in this case). 

The terminal type name received from the remote client is converted to lowercase. 

The packet interface to the pseudoterminal (see ptv(7)) should be used for more intelli- 
gent flushing of input and output queues. 

telnetd never sends TELNET go ahead commands. 

SEE ALSO 

telnet(lC) 
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NAME 

tftpd - tftp daemon 

SYNOPSIS 

/etc/tftpd 

DESCRIPTION 

tftpd is a daemon which runs the trivial file transfer protocol server for the SysV Inter- 
net software. It is called by inetd(lM) when an incoming datagram requests the 
tftp(lC) service. It then handles tftp(lC) file transfers in accordance with RFC783. 

Note that /etc/tftpd must be setuid to a designated tftp(lC) user (usually a very non- 
privileged userid and never root) and that the tftp(lC) spool directory must be owned 
by that user. 

NOTES 

The Domain/OS SysV versions of tftp(lC) and tftpd are adaptations of the Mas- 
sachusetts Institute of Technology implementations of the tftp protocol. Domain/OS 
SysV tftp will interface with any RFC783 compliant implementation. Note, however, 
that the 4.3BSD distribution version of tftp does not meet these restrictions. 

WARNINGS 

tftp(lC) and tftpd comprise an implementation of the Trivial File Transfer Protocol 
described in RFC783. They allow you to quickly copy files among hosts on an internet 
without regard to ownership or access restrictions. Therefore, the desired security of a 
system should be considered before allowing tftp(lC) transactions. In an inspired 
attempt to prevent accidental destruction of important files, tftp(lC) requires that 
remote file names be absolute pathnames (that is, beginning with f) containing the string 
“/tftp/”, but not containing the string “/../”. 

SEE ALSO 

tftp(lC), inetd(lM); 

Configuring and Managing TCPIIP. 
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NAME 

tic - terminfo compiler 

SYNOPSIS 

tic [ — v[n]] [-c] file 

DESCRIPTION 

tic translates a terminfo(4) file from the source format into the compiled format. The 
results are placed in the directory /usr/Iib/terminfo. The compiled format is necessary 
for use with the library routines described in curses(3X). 

OPTIONS 

— v n (verbose) 

Outputs trace information showing tic’s progress to standard error. The 
optional integer n is a number from 1 to 10, inclusive, indicating the 
desired level of detail of information. If n is omitted, the default level is 
1. If n is specified and greater than 1, the level of detail is increased. 

— c Checks only file for errors. Errors in use= links are not detected. 

file Contains one or more terminfo(4) terminal descriptions in source format 

(see terminfo(4)). Each description in the file describes the capabilities 
of a particular terminal. When a us e=entry-name field is discovered in a 
terminal entry currently being compiled, tic reads in the binary from 
/usr/Iib/terminfo to complete the entry. (Entries created from file are 
used first. If the environment variable TERMINFO is set, that directory 
is searched instead of /usr/Iib/terminfo.) tic duplicates the capabilities 
in entry-name for the current entry, with the exception of those capabili- 
ties that are defined explicitly in the current entry. If the environment 
variable TERMINFO is set, the compiled results are placed there instead 
of /usr/Iib/terminfo. 

NOTES 

Total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 128 
bytes. 

Terminal names exceeding 14 characters are truncated to 14 characters and a warning 
message are printed. 

When the — c option is used, duplicate terminal names are diagnosed; however, when — c 
is not used, they are. 

BUGS 

To allow existing executables from the previous release of the UNIX System to continue 
to run with the compiled terminfo entries created by the new terminfo compiler, can- 
celled capabilities are not marked as cancelled within the terminfo binary unless the 
entry name has a *+’ within it. (Such terminal names are used only for inclusion within 
other entries via a use= entry. Such names are not used for real terminal names.) 
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For example 

4415+nl, kf 10, kf 20, .... 

4415+base, kfl=\EOc, kf2=\E0d, .... 

4415-nl|4415 terminal without keys, 
use=4415+nl, use=4415+base, 

The above example works as expected; the definitions for the keys do not show up in 
the 4415-nl entry. However, if the entry 4415+nl did not have a plus sign within its 
name, the cancellations would not be marked within the compiled file and the 
definitions for the function keys would not be cancelled within 4415-nl. 

FILES 

/us r/lib/ter ininfo/?/* Compiled terminal description database 

DIAGNOSTICS 

Most diagnostic messages produced by tic during the compilation of the source file are 
preceded by the approximate line number and the name of the terminal currently being 
worked on. 

mkdir . . . returned bad status 

The named directory could not be created. 

File does not start with terminal names in column one 

The first thing seen in the file, after comments, must be the list of termi- 
nal names. 

Token after a seek (2) not NAMES 

Somehow the file being compiled changed during the compilation. 

Not enough memory for use_list element 
or 

Out of memory 

Not enough free memory was available (malloc(3) failed). 

Can' t open . . . 

The named file could not be created. 

Error in writing . . . 

The named file could not be written to. 

Can't link ... to ... 

A link failed. 

Error in re-reading compiled file . . . 

The compiled file could not be read back in. 
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Premature EOF 

The current entry ended prematurely. 

Backspaced off beginning of line 

This error indicates something wrong happened within tic. 

Unknown Capability - " . . . " 

The named invalid capability was found within the file. 

Wrong type used for capability " . . . " 

For example, a string capability was given a numeric value. 

Unknown token type 

Tokens must be followed by to cancel, V for booleans, ‘#’ for 
numbers, or *=’ for strings. 

bad term name 
or 

Line . . . : Illegal terminal name - " . . . " 

Terminal names must start with a letter or digit 

The given name was invalid. Names must not contain white space or 
slashes, and must begin with a letter or digit. 

terminal name too long. 

An extremely long terminal name was found. 

terminal name too short. 

A one-letter name was found. 

filename too long, truncating to 

The given name was truncated to 14 characters due to UNIX file name 
length limitations. 

" . . . " defined in more than one entry. 

Entry being used is 

An entry was found more than once. 

Terminal name " . . . " synonym for itself 

A name was listed twice in the list of synonyms. 

At least one synonym should begin with a letter. 

At least one of the names of the terminal should begin with a letter. 

Illegal character - " . . . " 

The given invalid character was found in the input file. 

Newline in middle of terminal name 

The trailing comma was probably left off of the list of names. 

Missing comma 

A comma was missing. 
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Missing numeric value 

The number was missing after a numeric capability. 

NULL string value 

The proper way to say that a string capability does not exist is to cancel 
it. 

Very long string found. Missing comma? 
self-explanatory 

Unknown option. Usage is: 

An invalid option was entered. 

Too many file names. Usage is: 
self-explanatory 

" . . . " non-existent or permission denied 
The given directory could not be written into. 

" . . . " is not a directory 
self-explanatory 

Permission denied 
access denied. 

Not a directory 

tic wanted to use the given name as a directory, but it already exists as a 
file 

SYSTEM ERROR! ! Fork failed! ! ! 

A fork(2) failed. 

Error in following up use-links. Either there is a loop in the links or they reference 
non-existent terminals. In the entries involved, a terminfo(4) entry with a us e=name 
capability referenced a non-existent terminal called name or name somehow referred 
back to the given entry. 

SEE ALSO 

curses(3X), term(4), terminfo(4) 
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NAME 

trpt - transliterate protocol trace 
SYNOPSIS 

trpt [ -a ] [ -c ] [ -d <PCB addr> ] [ -e ] [ -f ] [ -j ] [ -I ] 

[ -s ] [ -t ] [ — w ] [ -p <PCB addr> ] [ <filename> ] 

DESCRIPTION 

trpt interrogates the buffer of TCP trace records created when a socket is marked for 
“debugging” (see setsockopt(2)), and prints a readable description of these records. 
When no options are supplied, trpt prints all the trace records found in the system, 
grouped according to TCP connection protocol control block (PCB). The following 
options may be used to alter this behavior. 

OPTIONS 



-a 


Print the values of the source and destination addresses for each 
packet recorded, in addition to the normal output. 


-f 


Follow the trace as it occurs, waiting a short time for additional 
records each time the end of the log is reached. 


-j 


Just give a list of the protocol control block addresses for which 
there are trace records. 


-p <PCB addr> 


Show only trace records associated with the protocol control 
block, the address of which follows. 


-s 


Print a detailed description of the packet sequencing information, 
in addition to the normal output. (Currently unimplemented) 


-t 


Print the values for all timers at each point in the trace, in addi- 
tion to the normal output. (Currently unimplemented) 


Domain/OS SysV EXTENSIONS 


— c 


Clear trace buffer. 


-d <PCB addr> 


Toggle debug on a connection. 


-e 


Exit on a bad trace record. 


-1 


Print lapsed times, in addition to the normal output. 


-w 


Warn on bad trace records. 



NOTES 

The recommended use of trpt is as follows. Isolate the problem and enable debugging 
on the socket(s) involved in the connection. Find the address of the protocol control 
blocks associated with the sockets using the -A option to netstat(l). Then run trpt 
with the -p option, supplying the associated protocol control block addresses. The -f 
option can be used to follow the trace log once the trace is located. If there are many 
sockets using the debugging option, the -j option may be useful in checking to see if 
any trace records are present for the socket in question. 
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If debugging is being performed on a file other than the default, which is 
k node_data/systmp/tcp_data, <filename> may be used to specify another file. 

DIAGNOSTICS 

no namelist 

Printed when the system image doesn’t contain the proper symbols to find the trace 
buffer. 

Other diagnostics should be self explanatory. 

BUGS 

trpt should print the data for each input or output, but this is not saved in the race 
record. 

The output format is inscrutable. 

FILES 

k node_data/systmp/tcp_data 
SEE ALSO 

setsockopt(2), netstat( l); 

Configuring and Managing TCP/IP. 
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NAME 

uctnode - uncatalog a node 
SYNOPSIS 

/etc/uetnode [ options ] pathname ... 

DESCRIPTION 

uctnode removes the specified entry directory name from the local copy of the network 
root directory. After the name is removed, objects cataloged under that node’s entry 
directory are no longer accessible to you or other nodes on the network. 

If you use the —root option, the nodename is also removed from the network’s repli- 
cated root directory. 

Node entry directories are created with the ctnode command. 

pathname (required) Specify node entry directory name to be uncataloged. Multiple 

pathnames and wildcarding are permitted. 

OPTIONS 

—1 List directory names as they are uncataloged. 

—root Uncatalog the node in the network root as well as in the the local root direc- 
tory. 

EXAMPLES 

Uncatalog the node with the entry directory name specified. 

$ /etc/uctnode als node 
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NAME 

uctob -uncatalog the specified pathname, without deleting the associated object. 
SYNOPSIS 

/etc/uctob [ — br] pathname... 

DESCRIPTION 

The command uctob removes the specified pathname from the name space. The object 
associated with the pathname is not affected. This command is primarily intended for 
system-level debugging use. 

OPTIONS 

— br Suppress listing of names and uids of objects as they are unca- 

taloged. These are reported unless this option is specified. 

EXAMPLES 

$ /etc/uctob testfile 

"testfile" uid is 16791C0C.40000074. 

$ 

This example uncatalogs testfile. 
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NAME 

ulkob - unlock an object 
SYNOPSIS 

/etc/ulkob [ options ] [pathname ...] 

DESCRIPTION 

ulkob unlocks objects residing on, or locked by processes running on, the current node. 
You cannot unlock objects on remote nodes unless you locked them (see — f below). 

pathname (optional) 

Specify name of object to be unlocked. Multiple pathnames and wild- 
carding are permitted. 



Default if omitted: -u option must be specified 



OPTIONS 

If no options are specified, the object is unlocked for all lock modes. 

— r Unlock an object that was locked for read mode; the lock must be 

owned by this process. 

— w Unlock an object that was locked for write mode; the lock must be 

owned by this process. 

— i Unlock an object that was locked for reading with intent to write; the 

lock must be owned by this process. 

— f Forcibly unlock an object. It may have been locked for any mode and 

the lock may be owned by any process. The object must reside on the 
current node, however, or must have been locked by the current node. 
In other words, you cannot unlock objects on a remote node unless 
you locked them. 

—1 List the name of each object as it is unlocked. 

-u uid ... Specify the UID of the object(s) to unlock. Multiple UIDs are permit- 

ted. If the pathname argument is omitted, then this option is required. 

EXAMPLES 

Forcibly unlock the file niarv for any mode and unlock the two objects with the 

specified UIDs. 



$ /etc/ulkob mary-f 



$ /etc/ulkob -uid 1C1A9E2F.20000246 IC 1 A9E42.50000246 
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NAME 

uucheck - check the uucp directories and permissions file 
SYNOPSIS 

/usr/lib/uucp/uucheck [ -v ] [ — x debug Jevel ] 

DESCRIPTION 

uucheck checks for the presence of the uucp system required files and directories. 
Within the uucp makefile, it is executed before the installation takes place. It also 
checks for some obvious errors in the Permissions file (/usr/lib/uucp/Permissions). 

OPTIONS 

-v Gives a detailed explanation of how the uucp programs interpret the 

Permissions file. 

-x debug Jevel 

Used for debugging, debug Jevel is a single digit in the range 1-9; the 
higher the value, the greater the detail. 

NOTE 

uucheck can only be used by the super-user or uucp. 

BUGS 

The program does not check file/directory modes or some errors in the Permissions file, 
such as duplicate login or machine name. 

FILES 

/ us r/l i b/uucp/Systems 

/usr/lib/uucp/Permissions 

/usr/lib/uucp/Devices 

/usr/lib/uucp/Maxuuscheds 

/usr/lib/uucp/IMaxuuxqts 

/usr/spool/uucp/* 

/usr/spooI/locks/LCK* 

/usr/spool/uucppublic/* 

SEE ALSO 

uucico(lM), uusched(lM); 

uucp(lC) uustat(lC) uux(lC) in the SysV Command Reference. 
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NAME 

uucico - file transport program for the uucp system 
SYNOPSIS 

/usr/lib/uucp/uucico [ — r role_number ] [ -x debug Jevel ] [ -i interface ] 

[ -d spool directory ] -s systemjiame 

DESCRIPTION 

uucico is the file transport program for uucp work file transfers. Domain/OS systems 
supply two versions of uucico: uucico, which, when called simply exits, leaving your 
work in the queue, and uucico.real, which, as its name implies, is the “real” uucico 
program. Normally, uucico.real is invoked locally by cron, or when a remote host ini- 
tiates a uucp connection with the Domain/OS system in slave mode. Work queued by 
you is processed when uucico.real is invoked by either method. The only way to 
directly invoke uucico.real is to run it on the node on which it is installed. 

OPTIONS 

—rrole number 

role numbers for the master mode and slave mode. One for master 
mode or zero for slave mode (default), -r should be specified as the 
digit 1 for master mode when uucico is started by a program or cron, 
uux and uucp both queue jobs that are to be transferred by uucico. It is 
normally started by the scheduler, uusched, but can be started manually; 
this is done for debugging. For example, the shell Uutry starts uucico 
with debugging turned on. 

—xdebugjevel 

You must use a single digit for this option, with higher numbers for more 
debugging. 

— i interface Defines the interface used with uucico. This interface only affects slave 
mode. Known interfaces are the UNIX System (default), TLI (basic 
Transport Layer Interface), and TLIS (Transport Layer Interface with 
Streams modules, read/write). 

FILES 

/usr/lib/uucp/Svstems 

/usr/lib/uucp/Permissions 

/usr/lib/uucp/Devices 

/usr/lib/uucp/Devconfig 

/usr/lib/uucp/Sysfiles 

/usr/lib/uucp/Maxuuxqts 

/usr/Iib/uucp/Maxuuscheds 

/usr/spool/uuep/* 

/usr/spool/locks/LCK* 

/usr/spool/uucppublic/* 



9-202 



Commands 




UUCICO(IM) 



SysV 



UUCICO(IM) 



SEE ALSO 

cron(lM), uusched(lM), Uutry(lM); 

uucp(lC), uustat(lC), uux(lC), in the SysV Command Reference. 
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NAME 

uucleanup - uucp spool-directory clean-up 



SYNOPSIS 

/usr/lib/uucp/uucleanup [ — C time ] [ — W time ] [ —Xtime ] [ -m, string ] 

[ -o time ] [ -s system ] 

DESCRIPTION 

uucleanup scans the spool directories for old files and takes appropriate action to 
remove them in a useful way. uucleanup informs you of send/receive requests for sys- 
tems that cannot be reached. It returns mail that cannot be delivered. It deletes or exe- 
cutes rnews for mews type files (depending on whether the news originated locally or 
remotely), uucleanup removes all other files. 



In addition, you are warned about requests that have been waiting for a given number of 
days (the default is 1.) 



OPTIONS 

— Ctime 

-Dtime 

— W time 



—Xtime 

-m string 
-o time 

-s system 



Removes any C. files greater or equal to time days old and supplies you 
with the appropriate information, (the default is 7 days.) 

Removes any D. files greater or equal to time days old. Attempts to 
deliver mail messages and execute rnews when appropriate, (the default 
is 7 days.) 

Sends a mail messsage concerning any C. files equal to time days old 
warning about the delay in contacting the remote. The message includes 
the JOB ID, and in the case of mail, the mail message. The administrator 
can include a message line telling who to call to check the problem (see 
-m option), (the default is 1 day) 

Removes any X. files greater or equal to time days old. D. files are prob- 
ably not present (if they were, X. should have been executed). But if 
there are D. files, they are taken care of by D. processing, (the default is 
2 days.) 

Includes this line in the warning message generated by the — W option. 

Deletes other files older than time days old. (the default is 2 days.) The 
default line is "See your local administrator to locate the problem". 

Executes for system spool directory only. 



—xdebugjevel 

debug level is a single digit between 0 and 9; higher numbers give more 
detailed debugging information. (If uucleanup is compiled with 
-DSMALL, no debugging output is available.) This program is typically 
started by the shell uudemon.cleanup, which should be started by 
cron(lM). 
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NOTE 

uucleanup works as if all option times are specified to the default values unless you 
specifically set time. 

FILES 

/usr/lib/uucp 

Directory with commands used by uucleanup internally /usr/spool/uucp Spool direc- 
tory 

SEE ALSO 

cron (1M), uucp(lC), uux(lC) 
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NAME 

uuidgen - UUID generating program 
SYNOPSIS 

/etc/ncs/uuid_gen [ — c ] [ — p ] [ — C ] [ — P ] 

DESCRIPTION 

The uuid_gen program generates Universal Unique Identifiers (UUIDs). Without 
options, it generates a character-string representation of a UUID. The options enable 
you to generate templates for Network Interface Definition Language (NIDL) files or to 
generate source-code representations of UUIDs, suitable for initializing variables of 
type uuid_$t. 

OPTIONS 

— c Generate a template, including a UUID attribute, for an interface 

definition in the C syntax of NIDL. 

-p Generate a template, including a UUID attribute, for an interface 

definition in the Pascal syntax of NIDL. 

— C Generate a C source-code representation of a UUID. 

-P Generate a Pascal source-code representation of a UUID. 

EXAMPLES 

Generate a template for an interface definition in the C syntax of NIDL: 

$ /sys/ncs/uuid_gen -c 

%c 

[ 

uuid (34dc239ec000.0d. 00. 00. 7c. 5f .00.00.00) , 
version (1) 

] 

interface INTERFACENAME { 

Generate a C source-code representation of a UUID: 

$ /sys/ncs/uuid_gen -C 

= { 0x34dc23af, 

Oxf 000 , 

0x0000, 

OxOd, 

{0x00, 0x00 , 0x7c, 0x5 f, 0x00 , 0x00, 0x00 } } ; 
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NAME 

uusched - the scheduler for the uucp file transport program 
SYNOPSIS 

/usr/lib/uucp/uusched [ -\debug_level ] [ -u debugjevel ] 

DESCRIPTION 

uusched is the uucp file transport scheduler. It is usually started by the daemon 
uudemon.hour that is started by cron(lM) from an entry in /usr/spool/cron/crontab: 

39 * * * * /bin/su uucp -c "/usr/lib/uucp/ uudemon .hour > /dev/null" 

OPTIONS 

-\debug_level Causes debugging messages to be output from 

uusched. 

-udebugjevel Causes debugjevel to pass as -x debugjevel to 

uucico. debugjevel is a number between 0 and 9; 
higher numbers give more detailed information. 

NOTE 

The two options are for debugging purposes only. 

FILES 

/usr/lib/uucp/Systems 
/usr/lib/uucp/Permissions 
/ us r/l i b/uuc pi Devi ces 
/ us r/s pool/ uucp/* 

/usr/spool/locks/LC K* 

/usr/spool/uucppublic/* 

SEE ALSO 

cron(lM), uucico(lM), 

uucp(lC), uustat(lC), uux(lC), in the SysV Command Reference. 



Commands 



9-207 




UUXQT(IM) 



SysV 



UUXQT(IM) 



NAME 

uuxqt — execute remote command requests 
SYNOPSIS 

/usr/lib/uucp/uuxqt [ -s system ] [ -xdebuglevel ] 

DESCRIPTION 

uuxqt executes remote job requests from remote systems generated by the use of the 
uux command. (Mail uses uux for remote mail requests), uuxqt searches the spool 
directories looking for X. files. For each X. file, uuxqt checks to see if all the required 
data files are available and accessible, and file commands are permitted for the request- 
ing system, uuxqt uses the Permissions file to validate file accessibility and command 
execution permission. 

Two environment variables are set before uuxqt is executed: 

UU_MACHINE is the machine that sent the job (the previous one). 

UU_USER is the user that sent the job. 

These can be used in writing commands that remote systems can execute to provide 
information, auditing, or restrictions. 

debug Jevel is a single digit between 0 and 9. Higher numbers give more detailed 
debugging information. 

FILES 

/usr/lib/uucp/Permissions 

/usr/lib/uucp/Maxuuxqts 

/usr/spool/uucp/* 

/usr/spool/locks/LCK* 

SEE ALSO 

uucico(lM) 

uucp(lC), uustat(lC), uux(lC), mail(l), in the SysV Command Reference. 
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NAME 

ver - change version of shell commands 

SYNOPSIS 

ver 

ver systype 

ver systype command 

DESCRIPTION 

ver changes, temporarily or permanently, the UNIX version of commands that are exe- 
cuted by the shell. It also displays the version in use. 

The first form of ver (without arguments), displays the current systype value, which 
specifies the UNIX version of commands being executed by the shell. 

The second form allows you to set the UNIX version to systype. Valid systype s are 
“sys5” and “bsd4.2”. 

The third form of the command causes the UNIX version of command specified by sys- 
type to be executed, with no permanent change to systype. 

FILES 

/etc/ver Used for the third form of the command 
SEE ALSO 

SysV Command Reference. 
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NAME 

wall - write to all users on a node 

SYNOPSIS 

/etc/wall 

DESCRIPTION 

wall reads its standard input until an end-of-file (EOF), then sends the specified mes- 
sage to all users currently logged in on a particular node. The message is always pre- 
ceded by 

Broadcast Message from ... 

wall is helpful for notifying users of important information, and particularly for warn- 
ing them prior to a system shutdown. 

NOTE 

The sender must be super-user. 

FILES 

/dev/p ty* Device filenames 

/dev/sio* Device filenames 

DIAGNOSTICS 

' 'Cannot send to . . . ' ' 

> 

when the open on a user’s tty file fails. 

SEE ALSO 

write( 1 ) 
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NAME 

writed - server for vvrite(l) program 

SYNOPSIS 

/etc/wri ted 

DESCRIPTION 

The writed server is used by the write(l) program. To enable a write to a node other 
than your own, writed must be running on the destination node. Similarly, you must be 
running writed on your node to receive a write message. 

To invoke writed in background mode using the /etc/rc shell script, include the lines 

if [ -f /etc/writed ] ; then 
/etc/writed & 
fi 

in your node’s ‘node_data/etc.rc file. The /etc/run_rc program starts 
writed at boot time (after first checking to see if the file exists). 

The writed process starts mbx helper 

automatically if one is not present when writed is invoked. 

FILES 

/etc/utmp Record of who is logged in on the node (link to 

‘nodedata/etc.utmp). 

SEE ALSO 

write (1), utmp (4) 
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NAME 

intro — introduction to special files 
DESCRIPTION 

This section describes various special files that refer to specific hardware peripherals 
and device drivers. STREAMS (see intro(2)) software drivers, modules, and the 
STREAMS-generic set of ioctl(2) system calls are also described. 

For hardware related files, the names of the entries are generally derived from names 
for the hardware, as opposed to the names of the special files themselves. Characteris- 
tics of both the hardware device and the corresponding device driver are discussed 
where applicable. 

Disk device file names are in the following format: 

/dtn7{r}dsk/c#</#s# 

where r indicates a raw interface to the disk, the e# indicates the controller number, d# 
indicates the device attached to the controller and s# indicates the section number of the 
partitioned device. 
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NAME 

done - open any minor device on a STREAMS driver 
DESCRIPTION 

A device node corresponding to a STREAMS device may have the high bit of its minor 
device number set to 1 (256 decimal and higher, the minor device number is a 9-bit 
quantity); this indicates a cloneable device. 

An open(2) system call on a cloneable device opens a Stream to an unused minor dev- 
ice. The driver corresponding to the device node must recognize and respond correctly 
to a clone open. 

On SysV, the done facility is not implemented as a separate driver and corresponding 
device node(s). Cloning is only possible with STREAMS drivers. 

CAVEATS 

Multiple opens of the same minor device cannot be done through the done interface. 

SEE ALSO 

log(7) 

Programming with SysV STREAMS, for a discussion of the done mechanism. 



10-2 



Special Files 




CONSOLE(7) 



SysV 



CONSOLES) 



NAME 

console - console interface 
DESCRIPTION 

The console provides a place to write system messages. The file /dev/console is the sys- 
tem console. Output is placed in the file ‘node_data/system_logs/console. /etc/mkcon 
can be used to redirect console output to other devices or files. 

FILES 

/dev/console 

SEE ALSO 

inkcon (8) 
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NAME 

hdelog - hard disk error log interface file 
DESCRIPTION 

The file /dev/hdelog is a special file that provides access to the disk error logging 
mechanism, the equipped disk table, and the disk drivers of the equipped disks for 
doing physical (non-partitioned) disk I/O. It is an internal interface of bad block han- 
dling and a few other disk utilities and is not intended to be used directly by users. You 
must be super-user to use it. 

FILES 

/dev/hdelog 
SEE ALSO 

hdeadd(lM), hdefix(lM), hdelogger(lM). 



10-4 



Special Files 




LOG(7) 



SysV 



LOG(7) 



NAME 

log - interface to STREAMS error logging and event tracing 
DESCRIPTION 

log is a STREAMS software device driver that provides an interface for the STREAMS 
error logging and event tracing processes (strerr(lM), strace(lM)). log presents two 
separate interfaces: a function call interface through which STREAMS drivers and 
modules submit log messages; and a subset of ioctl(2) system calls and STREAMS mes- 
sages for interaction with a user level error logger, a trace logger, or processes that need 
to submit their own log messages. 

STREAMS Interface 

log messages are generated within STREAMS by calls to the function strlog: 



strlog(mid, sid, level, flags, fmt, argl, ...) 

short mid, sid; 

char level; 

ushort flags; 

char *fmt; 

unsigned argl; 

where: mid is the STREAMS module id number for the module or driver submitting the 
log message, sid is an internal sub-id number usually used to identify a particular 
minor device of a driver, level is a tracing level that allows for selective screening out 
of low priority messages from the tracer, flags are any combination of SL_ERROR (the 
message is for the error logger), SL_TRACE (the message is for the tracer), SL_FATAL 
(advisory notification of a fatal error), and SL_NOTIFY (request that a copy of the mes- 
sage be mailed to the system administrator — not implemented), fmt is a print f(3S) 
style format string, except that %s, %e, %E, %g, and %G conversion specifications are 
not handled. Up to NLOGARGS (currently 3) numeric or character arguments can be 
provided. Required definitions are contained in <sys/strlog.h> and <sys/log.h>. 

User Interface 

log is opened via /dev/logd. Each open of /dev/logd obtains a separate stream to log. 
To receive log messages, a process must first notify log whether it is an error logger or 
trace logger via a STREAMS I_STR ioctl call (see below). For the error logger, the 
I_STR ioctl has an ic_cmd field of I_ERRLOG, with no accompanying data. For the 
trace logger, the ioctl has an ic_cmd field of I_TRCLOG, and must be accompanied by a 
data buffer containing an array of one or more struct trace_ids elements. Each trace_ids 
structure specifies a mid, sid, and level from which message will be accepted, strlog 
accepts messages whose mid and sid exactly match those in the trace_ids structure, and 
whose level is less than or equal to the level given in the trace_ids structure. A value of 
- 1 in any of the fields of the trace_ids structure indicates that any value is accepted for 
that field. 
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At most one trace logger and one error logger can be active at a time. Once the logger 
process has identified itself via the ioctl call, log begins sending messages subject to the 
restrictions noted above. These messages are obtained via the getmsg(2) system call. 
The control part of this message contains a log_ctl structure, which specifies the mid, 
sid, level, flags, time in ticks since boot that the message was submitted, the 
corresponding time in seconds since Jan. 1, 1970, and a sequence number. The time in 
seconds since 1970 is provided so that the date and time of the message can be easily 
computed, and the time in ticks since boot is provided so that the relative timing of log 
messages can be determined. 

Different sequence numbers are maintained for the error and trace logging streams and 
are provided so that gaps in the sequence of messages can be determined (during times 
of high message traffic some messages may not be delivered by the logger to avoid hog- 
ging system resources). The data part of the message contains the unexpanded text of 
the fonnat string (null terminated), followed by NLOGARGS words for the arguments to 
the format string, aligned on the first word boundary following the format string. 

A process may also send a message of the same structure to log, even if it is not an error 
or trace logger. The only fields of the log_ctl structure in the control part of the mes- 
sage that are accepted are the level and flags fields; all other fields are filled in by log 
before being forwarded to the appropriate logger. The data portion must contain a null 
terminated format string, and any arguments (up to NLOGARGS) must be packed one 
word each, on the next word boundary following the end of the format string. 

Attempting to issue an I_TRCLOG or I_ERRLOG when a logging process of the given 
type already exists results in the error ENXIO being returned. Similarly, ENXIO is 
returned for I_TRCLOG ioctls without any trace_ids structures, or for any unrecognized 
I_STR ioctl calls. Incorrectly formatted log messages sent to the driver by a user pro- 
cess are silently ignored (no error results). 

EXAMPLES 

Example of I_ERRLOG notification. 



struct strioctl ioc; 
ioc.ic_cmd = I_ERRLOG; 

ioc . ic_timout =0; /* default timeout (15 secs.) 

ioc.ic_len = 0; 
ioc.ic_dp = NULL; 

ioctl (log, I_STR, &ioc) ; 
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Example of I_TRCLOG notification. 

struct trace_ids tid[2]; 

tid[0] .ti_mid = 2; 
tid[0] .ti_sid = 0; 
tid [0] . ti_level = 1; 

tid[l] .ti_mid = 1002; 
tid[l] . ti_sid = -1; 
tid[l] .ti_level = -1; 

ioc.ic_cmd = I_TRCLOG; 
ioc . ic_timout = 0; 
ioc.ic_len = 2 * sizeof (struct trace_ids) ; 
ioc.ic_dp = (char *)tid; 

ioctl(log / I_STR / &ioc) ; 

Example of submitting a log message (no arguments). 

struct strbuf ctl, dat; 
struct log_ctl lc; 

char ^message = "This is a message"; 

ctl.len = ctl.maxlen = sizeof (lc); 
ctl.buf = (char *)&lc; 

dat.len = dat.maxlen = strlen (message) ; 
dat.buf = message; 

lc. level = 0; 

lc. flags = SL_ERR0R | SL_N0TIFY ; 
putmsg(log, &ctl, &dat, 0); 

FILES 

/dev/logd, <sys/log.h>, <sys/strlog.h> 

SEE ALSO 

strace(IM), strerr(lM), tracem(7) 

intro(2), getmsg(2), putmsg(2) in the SysK Programmer’ s Reference. 
Programming with SysV STREAMS 



/* any sub-id will be allowed */ 
/* any level will be allowed */ 
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NAME 

mt - tape interface 
DESCRIPTION 

The files dev/rct8 and dev/rctl2 refer to cartridge tape controllers (CTC). The files 
dev/rmt8 and dev/rmtl2 refer to 9-track tape controllers. The rct8 and rmt8 controll- 
ers rewind on close; The ret 12 and rmtl2 do not. 

FILES 

/dev/rct8 

/dev/rctl2 

/dev/rmt8 

/dev/rmtI2 

SEE ALSO 

mt(lM) 
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NAME 

null - the null file 
DESCRIPTION 

Data written on the null special file, /dev/null, is discarded. 
Reads from a null special file always return 0 bytes. 

FILES 

/dev/null 
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NAME 

nulm — null STREAMS module 
DESCRIPTION 

nulm passes all messages it receives, unchanged, to the next module in the Stream. 
Messages are passed both upstream and downstream. 

The nulm module is useful for inserting a trace module at the top of a lower multi- 
plexed Stream for debugging purposes. 

SEE ALSO 

nuls(7), tracem(7), trconf(l) 
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NAME 

nuls - null STREAMS driver 

SYNOPSIS 

/dev/nuls 

DESCRIPTION 

nuls discards all data written to it (all downstream messages, except as noted below) 
and blocks indefinitely on reads. 

nuls provides canonical ioctl handling, by NAKing all M_IOCTL messages it receives. 
Canonical flush processing is also provided, i.e., nuls replies to an M_FLUSH message, 
if FLUSHRW is set, by sending a FLUSHR M_FLUSH message upstream. 

FILES 

/dev/nuls 

SEE ALSO 

nulm(7) 
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NAME 

streamio - STREAMS ioctl commands 



SYNOPSIS 

#intiude <stropts.h> 

int ioctl {ft Ides, command, arg) 
int fildes, command ; 

DESCRIPTION 

STREAMS (see intro(2)) ioctl commands are a subset of ioctl(2) system calls which 
perform a variety of control functions on Streams. The arguments command and arg 
are passed to the file designated by fildes and are interpreted by the Stream head. Cer- 
tain combinations of these arguments may be passed to a module or driver in the 
Stream. 



fildes is an open file descriptor that refers to a Stream, command determines the control 
function to be performed as described below, arg represents additional information 
that is needed by this command. The type of arg depends upon the command, but it is 
generally an integer or a pointer to a command- specific data structure. 

Since these STREAMS commands are a subset of ioctl, they are subject to the errors 
described there. In addition to those errors, the call will fail with errno set to EINVAL, 
without processing a control function, if the Stream referenced by fildes is linked below 
a multiplexor, or if command is not a valid value for a Stream. 

Also, as described in ioctl, STREAMS modules and drivers can detect errors. In this 
case, the module or driver sends an error message to the Stream head containing an 
error value. This causes subsequent system calls to fail with errno set to this value. 

COMMAND FUNCTIONS 

The following ioctl commands, with error values indicated, are applicable to all 
STREAMS files: 



I_PUSH 



Pushes the module whose name is pointed to by arg onto the top of the 
current Stream, just below the Stream head. It then calls the open rou- 
tine of the newly-pushed module. On failure, errno is set to one of the 
following values: 



[EINVAL] 

[EFAULT] 

[ENXIO] 

[ENXIO] 



Invalid module name. 

arg points outside the allocated address space. 
Open routine of new module failed. 

Hangup received on fildes. 
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I_POP Removes the module just below the Stream head of the Stream pointed 

to by fildes. arg should be 0 in an I_POP request. On failure, errno is 
set to one of the following values: 

[EINVAL] No module present in the Stream. 

[ENXIO] Hangup received on fildes. 

I_LOOK Retrieves the name of the module just below the Stream head of the 

Stream pointed to by fildes, and places it in a null terminated character 
string pointed at by arg. The buffer pointed to by arg should be at least 
FMNAMESZ+1 bytes long. An "#include <sys/conf.h>" declaration is 
required. On failure, errno is set to one of the following values: 

[EFAULT] arg points outside the allocated address space. 

[EINVAL] No module present in Stream. 

LFLUSH This request flushes all input and/or output queues, depending on the 
value of arg. Legal arg values are: 

FLUSHR Rush read queues. 

FLUSHW Flush write queues. 

FLUSHRW Flush read and write queues. 

On failure, errno is set to one of the following values: 

[EAGAIN] Unable to allocate buffers for flush message. 

[EINYAL] Invalid arg value. 

[ENXIO] Hangup received on fildes. 

LSETSIG Informs the Stream head that the user wishes the kernel to issue the 
SIGPOLL signal (see signal(2) and sigset(2)) when a particular event 
has occurred on the Stream associated with fildes. I_SETSIG supports 
an asynchronous processing capability in STREAMS. The value of arg 
is a bitmask that specifies the events for which the user should be sig- 
naled. It is the bitwise-OR of any combination of the following con- 
stants: 

S_INPUT A non-priority message has arrived on a Stream head 

read queue, and no other messages existed on that 
queue before this message was placed there. This is set 
even if the message is of zero length. 

S_HIPRI A priority message is present on the Stream head read 

queue. This is set even if the message is of zero length. 

S_OUTPUT The write queue just below the Stream head is no 
longer full. This notifies the user that there is room on 
the queue for sending (or writing) data downstream. 
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I_GETSIG 



I FIND 



I PEEK 



S_MSG A STREAMS signal message that contains the SIGPOLL 

signal has reached the front of the Stream head read 
queue. 

A user process may choose to be signaled only of priority messages by 
setting the arg bitmask to the value S_HIPRI. 

Processes that wish to receive SIGPOLL signals must explicitly register 
to receive them using I_SETSIG. If several processes register to receive 
this signal for the same event on the same Stream, each process will be 
signaled when the event occurs. 

If the value of arg is zero, the calling process will be unregistered and 
will not receive further SIGPOLL signals. On failure, errno is set to 
one of the following values: 

[EINVAL] arg value is invalid or arg is zero and process is not 
registered to receive the SIGPOLL signal. 

[EAGAIN] Allocation of a data structure to store the signal request 
failed. 

Returns the events for which the calling process is currently registered 
to be sent a SIGPOLL signal. The events are returned as a bitmask 
pointed to by arg, where the events are those specified in the descrip- 
tion of I_SETSIG above. On failure, errno is set to one of the following 
values: 

[EINVAL] Process not registered to receive the SIGPOLL signal. 

[EFAULT] arg points outside the allocated address space. 

This request compares the names of all modules currently present in the 
Stream to the name pointed to by arg, and returns 1 if the named 
module is present in the Stream. It returns 0 if the named module is not 
present. On failure, errno is set to one of the following values: 

[EFAULT] arg points outside the allocated address space. 

[EINVAL] arg does not contain a valid module name. 

This request allows a user to retrieve the information in the first mes- 
sage on the Stream head read queue without taking the message off the 
queue, arg points to a strpeek structure which contains the following 
members: 

struct strbuf ctlbuf; 

struct strbuf databuf; 

long flags; 
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I SRDOPT 



I GRDOPT 



I NR E AD 



IJFDINSERT 



The maxlen field in the ctlbuf and databuf strbuf structures (see 
getmsg(2)) must be set to the number of bytes of control information 
and/or data information, respectively, to retrieve. If the user sets flags 
to RS_HIPRI, I_PEEK will only look for a priority message on the 
Stream head read queue. 

I_PEEK returns 1 if a message was retrieved, and returns 0 if no mes- 
sage was found on the Stream head read queue, or if the RS_HIPRI flag 
was set in flags and a priority message was not present on the Stream 
head read queue. It does not wait for a message to arrive. On return, 
ctlbuf specifies information in the control buffer, databuf specifies 
information in the data buffer, and flags contains the value 0 or 
RSJHIPRI. On failure, errno is set to the following value: 

[EFAULT] arg points, or the buffer area specified in ctlbuf or 
databuf is, outside the allocated address space. 

Sets the read mode using the value of the argument arg. Legal arg 
values are: 

RNORM Byte-stream mode, the default. 

RMSGD Message-discard mode. 

RMSGN Message-nondiscard mode. 

Read modes are described in read(2). On failure, errno is set to the 
following value: 

[EINVAL] arg is not one of the above legal values. 

Returns the current read mode setting in an int pointed to by the argu- 
ment arg. Read modes are described in read(2). On failure, errno is 
set to the following value: 

[EFAULT] arg points outside the allocated address space. 

Counts the number of data bytes in data blocks in the first message on 
the Stream head read queue, and places this value in the location 
pointed to by arg. The return value for the command is the number of 
messages on the Stream head read queue. For example, if zero is 
returned in arg, but the ioctl return value is greater than zero, this indi- 
cates that a zero-length message is next on the queue. On failure, 
errno is set to the following value: 

[EFAULT] arg points outside the allocated address space. 

creates a message from user specified buffer(s), adds information about 
another Stream and sends the message downstream. The message con- 
tains a control part and an optional data part. The data and control parts 
to be sent are distinguished by placement in separate buffers, as 
described below. 
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arg points to a strfdinsert structure which contains the following 
members: 

struct strbuf ctlbuf; 

struct strbuf databuf; 

long flags; 

int fd; 

int offset; 

The len field in the ctlbuf strbuf structure (see putmsg(2)) must be set 
to the size of a pointer plus the number of bytes of control information 
to be sent with the message, fd specifies the file descriptor of the other 
Stream and offset, which must be word-aligned, specifies the number of 
bytes beyond the beginning of the control buffer where IJFDINSERT 
will store a pointer to the fd Stream’s driver read queue structure. The 
len field in the databuf strbuf structure must be set to the number of 
bytes of data information to be sent with the message or zero if no data 
part is to be sent. 

flags specifies the type of message to be created. A non-priority mes- 
sage is created if flags is set to 0, and a priority message is created if 
flags is set to RS_HIPRI. For non-priority messages, I_FDINSERT will 
block if the Stream write queue is full due to internal flow control con- 
ditions. For priority messages, I_FDINSERT does not block on this con- 
dition. For non-priority messages, I_FDINSERT does not block when 
the write queue is full and 0_NDELAY is set. Instead, it fails and sets 
errno to EAGAIN. 

I_FDINSERT also blocks, unless prevented by lack of internal 
resources, waiting for the availability of message blocks in the Stream, 
regardless of priority or whether 0_NDELAY has been specified. No 
partial message is sent. On failure, errno is set to one of the following 
values: 

[EAGAIN] A non-priority message was specified, the 0_NDELAY 
flag is set, and the Stream write queue is full due to 
internal flow control conditions. 

[EAGAIN] Buffers could not be allocated for the message that was 
to be created. 

[EFAULT] arg points, or the buffer area specified in ctlbuf or 
databuf is, outside the allocated address space. 
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[EINVAL] One of the following: fd in the strfdinsert structure is 
not a valid, open Stream file descriptor; the size of a 
pointer plus offset is greater than the len field for the 
buffer specified through ctlptr; offset does not specify 
a properly-aligned location in the data buffer; an 
undefined value is stored in flags. 

[ENXIO] Hangup received on fildes. 

[ERANGE] The len field for the buffer specified through databuf 
does not fall within the range specified by the max- 
imum and minimum packet sizes of the topmost Stream 
module, or the len field for the buffer specified through 
databuf is larger than the maximum configured size of 
the data part of a message, or the len field for the buffer 
specified through ctlbuf is larger than the maximum 
configured size of the control part of a message. 

I_STR Constructs an internal STREAMS ioctl message from the data pointed to 

by arg, and sends that message downstream. 

This mechanism is provided to send user ioctl requests to downstream 
modules and drivers. It allows information to be sent with the ioctl, 
and will return to the user any information sent upstream by the down- 
stream recipient. I_STR blocks until the system responds with either a 
positive or negative acknowledgement message, or until the request 
"times out" after some period of time. If the request times out, it fails 
with errno set to ETIME. 

At most, one I_STR can be active on a Stream. Further I_STR calls will 
block until the active I_STR completes at the Stream head. The default 
timeout interval for these requests is 15 seconds. The 0_NDELAY (see 
open(2)) flag has no effect on this call. 

To send requests downstream, arg must point to a strioctl structure 
which contains the following members: 



int 


ic_cmd; 


/* downstream command */ 


int 


ic_timout; 


/* ACK/NAK timeout */ 


int 


ic_len; 


/* length of data arg */ 


char 


*ic_dp; 


/* ptr to data arg */ 



ic_cmd is the internal ioctl command intended for a downstream 
module or driver and ie_timoi.it is the number of seconds (—1 = infinite, 
0 = use default, >0 = as specified) an I_STR request will wait for ack- 
nowledgement before timing out. 
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LSENDFD 



ic_len is the number of bytes in the data argument and ic_dp is a 
pointer to the data argument. The ic_len field has two uses: on input, it 
contains the length of the data argument passed in, and on return from 
the command, it contains the number of bytes being returned to the user 
(the buffer pointed to by ic_dp should be large enough to contain the 
maximum amount of data that any module or the driver in the Stream 
can return). 



The Stream head will convert the information pointed to by the strioctl 
stmcture to an internal ioctl command message and send it down- 
stream. On failure, errno is set to one of the following values: 



[EAGAIN] 

[EFAULT] 



[EINVAL] 



[ENXIO] 

[ETIME] 



Unable to allocate buffers for the ioctl message. 

arg points, or the buffer area specified by ic_dp and 
ic_len (separately for data sent and data returned) is, 
outside the allocated address space. 

icjen is less than 0 or icjen is larger than the max- 
imum configured size of the data part of a message or 
ic_timout is less than -1. 

Hangup received on fildes. 

A downstream ioctl timed out before acknowledgement 
was received. 



An I_STR can also fail while waiting for an acknowledgement if a mes- 
sage indicating an error or a hangup is received at the Stream head. In 
addition, an error code can be returned in the positive or negative ack- 
nowledgement message, in the event the ioctl command sent down- 
stream fails. For these cases, I_STR will fail with errno set to the value 
in the message. 

Requests the Stream associated with fildes to send a message, contain- 
ing a file pointer, to the Stream head at the other end of a Stream pipe. 
The file pointer corresponds to arg, which must be an integer file 
descriptor. 

LSENDFD converts arg into the corresponding system file pointer. It 
allocates a message block and inserts the file pointer in the block. The 
user id and group id associated with the sending process are also 
inserted. This message is placed directly on the read queue (see 
intro(2)) of the Stream head at the other end of the Stream pipe to 
which it is connected. On failure, errno is set to one of the following 
values: 



10-18 



Special Files 




STREAMIO(7) 



SysV 



STREAMIO(7) 



I RECVFD 



[EAGAIN] 

[EAGAIN] 

[EBADF] 

[EINVAL] 

[ENXIO] 



The sending Stream is unable to allocate a message 
block to contain the file pointer. 

The read queue of the receiving Stream head is full and 
cannot accept the message sent by I_SENDFD. 

arg is not a valid, open file descriptor. 

fildes is not connected to a Stream pipe. 

Hangup received on fildes. 



Retrieves the file descriptor associated with the message sent by an 
I_SENDFD ioctl over a Stream pipe, arg is a pointer to a data buffer 
large enough to hold an strrecvfd data structure containing the follow- 
ing members: 



int fd; 

unsigned short uid; 
unsigned short gid; 
char fill[8]; 

fd is an integer file descriptor, uid and gid are the user id and group id, 
respectively, of the sending Stream. 

If 0_NDELAY is not set (see open(2)), I_RECVFD will block until a 
message is present at the Stream head. If OJNDELAY is set, I_RECVFD 
will fail with errno set to EAGAIN if no message is present at the 
Stream head. 

If the message at the Stream head is a message sent by an I_SENDFD, a 
new user file descriptor is allocated for the file pointer contained in the 
message. The new file descriptor is placed in the fd field of the 
strrecvfd structure. The structure is copied into the user data buffer 
pointed to by arg. On failure, errno is set to one of the following 
values: 



[EAGAIN] 

[EBADMSG] 

[EFAULT] 

[EMFILE] 

[ENXIO] 



A message was not present at the Stream head read 
queue, and the 0_NDELAY flag is set. 

The message at the Stream head read queue was not a 
message containing a passed file descriptor. 

arg points outside the allocated address space. 

NOFILES file descriptors are currently open. 

Hangup received on fildes. 
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The following two commands are used for connecting and disconnecting multiplexed 
STREAMS configurations. 

I_LINK Connects two Streams, where fildes is the file descriptor of the Stream 

connected to the multiplexing driver, and arg is the file descriptor of 
the Stream connected to another driver. The Stream designated by arg 
gets connected below the multiplexing driver. I_LINK requires the mul- 
tiplexing driver to send an acknowledgement message to the Stream 
head regarding the linking operation. This call returns a multiplexor ID 
number (an identifier used to disconnect the multiplexor, see 
IJJNLINK) on success, and a -1 on failure. On failure, errno is set to 
one of the following values: 

[ENXIO] Hangup received on fildes. 

[ETIME] Time out before acknowledgement message was 

received at Stream head. 

[EAGAIN] Unable to allocate STREAMS storage to perform the 
I_LINK. 

[EBADF] arg is not a valid, open file descriptor. 

[EINVAL] The Stream identified by fildes does not support multi- 
plexing. 

[EINVAL] arg is not a Stream, or is already linked under a multi- 
plexor. 

[EINVAL] The specified link operation would cause a "cycle" in 
the resulting configuration; that is, if a given Stream 
head is linked into a multiplexing configuration in more 
than one place. 

An I_LINK can also fail while waiting for the multiplexing driver to 
acknowledge the link request, if a message indicating an error or a 
hangup is received at the Stream head of fildes. In addition, an error 
code can be returned in the positive or negative acknowledgement mes- 
sage. For these cases, I_LINK will fail with errno set to the value in the 
message. 

LUNLINK Disconnects the two Streams specified by fildes and arg. fildes is the 
file descriptor of the Stream connected to the multiplexing driver, arg 
is the multiplexor ID number that was returned by the ioctl I_LINK 
command when a Stream was linked below the multiplexing driver. If 
arg is -1, then all Streams which were linked to fildes are disconnected. 
As in I_LINK, this command requires the multiplexing driver to ack- 
nowledge the unlink. On failure, errno is set to one of the following 
values: 
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[ENXIO] Hangup received on fildes. 

[ETIME] Time out before acknowledgement message was 

received at Stream head. 

[EAGAIN] Unable to allocate buffers for the acknowledgement 
message. 

[EINVAL] Invalid multiplexor ID number. 

An I_UNLINK can also fail while waiting for the multiplexing driver to 
acknowledge the link request, if a message indicating an error or a 
hangup is received at the Stream head, of fildes. In addition, an error 
code can be returned in the positive or negative acknowledgement mes- 
sage. For these cases, I_UNLINK will fail with errno set to the value in 
the message. 

RETURN VALUE 

Unless specified otherwise above, the return value from ioctl is 0 upon success and -1 
upon failure with errno set as indicated. 

SEE ALSO 

close(2), fcntl(2), intro(2), ioctl(2), open(2), read(2), getmsg(2), poll(2), putmsg(2), sig- 
nal(2), sigset(2), write(2) in the SysV Programmer’ s Reference 
Programming with SysV STREAMS 
Gening Started with SysV STREAMS 
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NAME 

termio - general terminal interface 
DESCRIPTION 

All of the asynchronous communications ports use the same general interface, no matter 
what hardware is involved. The remainder of this section discusses the common 
features of this interface. 

When a terminal file is opened, it normally causes the process to wait until a connection 
is established. In practice, users’ programs seldom open terminal files; they are opened 
by getty and become a user’s standard input, output, and error files. The very first ter- 
minal file opened by the process group leader of a terminal file not already associated 
with a process group becomes the control terminal for that process group. The control 
terminal plays a special role in handling quit and interrupt signals, as discussed below. 
The control terminal is inherited by a child process during a fork (2). A process can 
break this association by changing its process group using setpgrp (2). 

A terminal associated with one of these files ordinarily operates in full-duplex mode. 
Characters may be typed at any time, even while output is occurring, and are only lost 
when the system’s character input buffers become completely full, which is rare, or 
when the user has accumulated the maximum allowed number of input characters that 
have not yet been read by some program. Currently, this limit is 256 characters. When 
the input limit is reached, new input characters are thrown away without notice. 

Normally, terminal input is processed in units of lines. A line is delimited by a new- 
line (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line char- 
acter. This means that a program attempting to read will be suspended until an entire 
line has been typed. Also, no matter how many characters are requested in the read 
call, at most one line will be returned. It is not, however, necessary to read a whole line 
at once; any number of characters may be requested in a read, even one, without losing 
information. 

During input, erase and kill processing is normally done. By default, Control-h erases 
the last character typed, except that it will not erase beyond the beginning of the line. 
By default, Control-u kills (deletes) the entire input line, and optionally outputs a new- 
line character. Both these characters operate on a key-stroke basis, independently of 
any backspacing or tabbing that may have been done. Both the erase and kill characters 
may be entered literally by preceding them with the escape character (\). In this case 
the escape character is not read. The erase and kill characters may be changed. 

Certain characters have special functions on input. These functions and their default 
character values are summarized as follows: 

INTR (Control-c) generates an interrupt signal which is sent to all processes with 
the associated control terminal. Normally, each such process is forced to ter- 
minate, but arrangements may be made either to ignore the signal or to 
receive a trap to an agreed-upon location; see signal (2). 
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QUIT (Control-) or ASCII FS) generates a quit signal. Its treatment is identical to 
the interrupt signal. 

ERASE (Control-h) erases the preceding character. It will not erase beyond the start 
of a line, as delimited by a NL, EOF, or EOL character. 

KILL (Control-u) deletes the entire line, as delimited by a NL, EOF, or EOL charac- 
ter. 

EOF (Control-d or ASCII EOT) may be used to generate an end-of-file from a ter- 
minal. When received, all the characters waiting to be read are immediately 
passed to the program, without waiting for a new-line, and the EOF is dis- 
carded. Thus, if there are no characters waiting, which is to say the EOF 
occurred at the beginning of a line, zero characters will be passed back, which 
is the standard end-of-file indication. 

NL (ASCII LF) is the normal line delimiter. It can not be changed or escaped. 

EOL (ASCII NUL) is an additional line delimiter, like NL. It is not normally used. 

STOP (Control-s or ASCII DC3) can be used to temporarily suspend output. It is use- 

ful with CRT terminals to prevent output from disappearing before it can be 
read. While output is suspended, STOP characters are ignored and not read. 

START (Control-q or ASCII DC1) is used to resume output which has been suspended 
by a STOP character. While output is not suspended, START characters are 
ignored and not read. The start/stop characters can not be changed or 
escaped. 

The character values for INTR, QUIT, SWTCH, ERASE, KELL, EOF, and EOL may be 
changed to suit individual tastes. The ERASE, KILL, and EOF characters may be 
escaped by a preceding \ character, in which case no special function is done. 

When the carrier signal from the data-set drops, a hang-up signal is sent to all processes 
that have this terminal as the control terminal. Unless other arrangements have been 
made, this signal causes the processes to terminate. If the hang-up signal is ignored, 
any subsequent read returns with an end-of-file indication. Thus, programs that read a 
terminal and test for end-of-file can terminate appropriately when hung up on. 

When one or more characters are written, they are transmitted to the terminal as soon as 
previously-written characters have finished typing. Input characters are echoed by put- 
ting them in the output queue as they arrive. If a process produces characters more 
rapidly than they can be typed, it will be suspended when its output queue exceeds 
some limit. When the queue has drained down to some threshold, the program is 
resumed. 
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Several ioctl (2) system calls apply to terminal files. The primary calls use the follow- 
ing structure, defined in <termio.h>: 

#define NCC 8 
struct termio { 

unsigned short c_iflag; /* input modes */ 

unsigned short c_oflag; /* output modes */ 

unsigned short c_cflag; /* control modes */ 

unsigned short c_lflag; /* local modes */ 

char c_line; /* line discipline */ 

unsigned char c_cc[NCC];/* control chars */ 

}; 

The special control characters are defined by the array c_cc. The relative positions and 
initial values for each function are as follows: 

0 VINTR DEL 

1 VQUIT FS 

2 VERASE # 

3 VKILL @ 

4 VEOF EOT 

5 VEOL NUL 

6 reserved 

7 SWTCH 

The cjflag field describes the basic terminal input control: 

IGNBRK 0000001 Ignore break condition. 

BRKINT 0000002 Signal interrupt on break. 

IGNPAR 0000004 Ignore characters with parity errors. 

PARMRK 00000 10 Mark parity errors. 

INPCK 0000020 Enable input parity check. 

ISTRIP 0000040 Strip character. 

INLCR 0000100 Map NL to CR on input. 

IGNCR 0000200 Ignore CR. 

ICRNL 0000400 Map CR to NL on input. 

IUCLC 0001000 Map upper-case to lower-case on input. 

IXON 0002000 Enable start/stop output control. 

IXANY 0004000 Enable any character to restart output. 

IXOFF 0010000 Enable start/stop input control. 

If IGNBRK is set, the break condition (a character framing error with data all zeros) is 
ignored, that is, not put on the input queue and therefore not read by any process. Oth- 
erwise if BRKINT is set, the break condition will generate an interrupt signal and flush 
both the input and output queues. If IGNPAR is set, characters with other framing and 
parity errors are ignored. 
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If PARMRK is set, a character with a framing or parity error which is not ignored is read 
as the three-character sequence: 0377, 0, X, where X is the data of the character 
received in error. To avoid ambiguity in this case, if ISTRIP is not set, a valid character 
of 0377 is read as 0377, 0377. If PARMRK is not set, a framing or parity error which is 
not ignored is read as the character NUL (0). 

If INPCK is set, input parity checking is enabled. If INPCK is not set, input parity 
checking is disabled. This allows output parity generation without input parity errors. 

If ISTRIP is set, valid input characters are first stripped to 7-bits, otherwise all 8-bits are 
processed. 

If INLCR is set, a received NL character is translated into a CR character. If IGNCR is 
set, a received CR character is ignored (not read). Otherwise if ICRNL is set, a received 
CR character is translated into a NL character. 

If IUCLC is set, a received upper-case alphabetic character is translated into the 
corresponding lower-case character. 

If EXON is set, start/stop output control is enabled. A received STOP character will 
suspend output and a received START character will restart output. All start/stop char- 
acters are ignored and not read. If IXANY is set, any input character, will restart output 
which has been suspended. 

If IXOFF is set, the system will transmit START/STOP characters when the input queue 
is nearly empty /full. 

The initial input control value is ICRNL, ISTRIP. 

The c_oflag field specifies the system treatment of output: 



OPOST 


0000001 


Postprocess output. 


OLCUC 


0000002 


Map lower case to upper on output 


ONLCR 


0000004 


Map NL to CR-NL on output. 


OCRNL 


0000010 


Map CR to NL on output. 


ONOCR 


0000020 


No CR output at column 0. 


ONLRET 


0000040 


NL performs CR function. 


OFILL 


0000100 


Use fill characters for delay. 


OFDEL 


0000200 


Fill is DEL, else NUL. 


NLDLY 


0000400 


Select new-line delays: 


NL0 


0 




NL1 


0000400 




CRDLY 


0003000 


Select carriage-return delays: 


CR0 


0 




CR1 


0001000 




CR2 


0002000 




CR3 


0003000 




TABDLY 


0014000 


Select horizontal-tab delays: 


TAB0 


0 





Special Files 



10-25 




TERMIO(7) 



SysV 



TERMIO(7) 



TAB1 


0004000 




TAB2 


0010000 




TAB3 


0014000 


Expand tabs to spaces. 


BSDLY 


0020000 


Select backspace delays: 


BS0 


0 




BS1 


0020000 




VTDLY 


0040000 


Select vertical-tab delays: 


VT0 


0 




VT1 


0040000 




FFDLY 


0100000 


Select form-feed delays: 


FF0 


0 




FF1 


01 00000 





If OPOST is set, output characters are post-processed as indicated by the remaining 
flags, otherwise characters are transmitted without change. 

If OLCUC is set, a lower-case alphabetic character is transmitted as the corresponding 
upper-case character. This function is often used in conjunction with IUCLC. 

If ONLCR is set, the NL character is transmitted as the CR-NL character pair. If OCRNL 
is set, the CR character is transmitted as the NL character. If ONOCR is set, no CR char- 
acter is transmitted when at column 0 (first position). If ONLRET is set, the NL charac- 
ter is assumed to do the carriage-return function; the column pointer will be set to 0 and 
the delays specified for CR will be used. Otherwise the NL character is assumed to do 
just the line-feed function; the column pointer will remain unchanged. The column 
pointer is also set to 0 if the CR character is actually transmitted. 

The delay bits specify how long transmission stops to allow for mechanical or other 
movement when certain characters are sent to the terminal. In all cases a value of 0 
indicates no delay. If OFILL is set, fill characters will be transmitted for delay instead 
of a timed delay. This is useful for high baud rate terminals which need only a minimal 
delay. If OFDEL is set, the fill character is DEL, otherwise NUL. 

If a form-feed or vertical -tab delay is specified, it lasts for about 2 seconds. 

New-line delay lasts about 0.10 seconds. If ONLRET is set, the carriage-return delays 
are used instead of the new-line delays. If OFILL is set, two fill characters will be 
transmitted. 

Carriage-return delay type 1 is dependent on the current column position, type 2 is 
about 0.10 seconds, and type 3 is about 0.15 seconds. If OFILL is set, delay type 1 
transmits two fill characters, and type 2, four fill characters. 

Horizontal-tab delay type 1 is dependent on the current column position. Type 2 is 
about 0.10 seconds. Type 3 specifies that tabs are to be expanded into spaces. If OFILL 
is set, two fill characters will be transmitted for any delay. 

Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill character will be 
transmitted. 
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The actual delays depend on line speed and system load. 
The initial output control value is OPOST, ONLCR. 



The c_cflag field describes the 


hardware control of the terminal: 


CBAUD 


0000017 


Baud rate: 


BO 


0 


Hang up 


B50 


0000001 


50 baud 


B75 


0000002 


75 baud 


B110 


0000003 


1 10 baud 


B134 


0000004 


134 baud 


B150 


0000005 


150 baud 


B200 


0000006 


200 baud 


B300 


0000007 


300 baud 


B600 


0000010 


600 baud 


B1200 


00000 11 


1200 baud 


B 1800 


0000012 


1800 baud 


B2400 


0000013 


2400 baud 


B4800 


0000014 


4800 baud 


B9600 


0000015 


9600 baud 


B 19200 


0000016 


19200 baud 


EXTA 


0000016 


External A 


B 3 8400 


0000017 


38400 baud 


EXTB 


0000017 


External B 


CSIZE 


0000060 


Character size: 


CS5 


0 


5 bits 


CS6 


0000020 


6 bits 


CS7 


0000040 


7 bits 


CS8 


0000060 


8 bits 


CSTOPB 


0000100 


Send two stop bits, else one. 


CREAD 


0000200 


Enable receiver. 


PARENB 


0000400 


Parity enable. 


PARODD 


0001000 


Odd parity, else even. 


HUPCL 


0002000 


Hang up on last close. 


CLOCAL 


0004000 


Local line, else dial-up. 


RCV1EN 


0010000 




XMT1EN 


0020000 




LOBLK 


0040000 


Block layer output. 



The CBAUD bits specify the baud rate. The zero baud rate, BO, is used to hang up the 
connection. If BO is specified, the data-terminal-ready signal will not be asserted. Nor- 
mally, this will disconnect the line. For any particular hardware, impossible speed 
changes are ignored. 

The CSIZE bits specify the character size in bits for both transmission and reception. 
This size does not include the parity bit, if any. If CSTOPB is set, two stop bits are 
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used, otherwise one stop bit. For example, at 1 10 baud, two stops bits are required. 

If PARENB is set, parity generation and detection is enabled and a parity bit is added to 
each character. If parity is enabled, the PARODD flag specifies odd parity if set, other- 
wise even parity is used. 

If CREAD is set, the receiver is enabled. Otherwise no characters will be received. 

If HUPCL is set, the line will be disconnected when the last process with the line open 
closes it or terminates. That is, the data-terminal-ready signal will not be asserted. 

If CLOCAL is set, the line is assumed to be a local, direct connection with no modem 
control. Otherwise modem control is assumed. 



If LOBLK is set, the output of a job control layer will be blocked when it is not the 
current layer. Otherwise the output generated by that layer will be multiplexed onto the 
current layer. 

The initial hardware control value after open is B9600, CS8, CREAD 



The c_lflag field of the argument structure is used by the line discipline to control ter- 
minal functions. The basic line discipline (0) provides the following: 



ISIG 


0000001 


ICANON 


0000002 


XCASE 


0000004 


ECHO 


0000010 


ECHOE 


0000020 


ECHOK 


0000040 


ECHONL 


0000100 


NOFLSH 


0000200 



Enable signals. 

Canonical input (erase and kill processing). 
Canonical upper/lower presentation (not supported). 
Enable echo. 

Echo erase character as BS-SP-BS. 

Echo NL after kill character. 

Echo NL. 

Disable flush after interrupt or quit. 



If ISIG is set, each input character is checked against the special control characters 
INTR, SWTCH, and QUIT. If an input character matches one of these control characters, 
the function associated with that character is performed. If ISIG is not set, no checking 
is done. Thus these special input functions are possible only if ISIG is set. These func- 
tions may be disabled individually by changing the value of the control character to an 
unlikely or impossible value (e.g., 0377). 



If ICANON is set, canonical processing is enabled. This enables the erase and kill edit 
functions, and the assembly of input characters into lines delimited by NL, EOF, and 
EOL. If ICANON is not set, read requests are satisfied directly from the input queue. A 
read will not be satisfied until at least MIN characters have been received or the timeout 
value TIME has expired between characters. This allows fast bursts of input to be read 
efficiently while still allowing single character input. The MIN and TIME values are 
stored in the position for the EOF and EOL characters, respectively. The time value 
represents tenths of seconds. 



If ECHO is set, characters are echoed as received. 
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When ICANON is set, the following echo functions are possible. If ECHO and ECHOE 
are set, the erase character is echoed as ASCII BS SP BS, which will clear the last char- 
acter from a CRT screen. If ECHOE is set and ECHO is not set, the erase character is 
echoed as ASCII SP BS. If ECHOK is set, the NL character will be echoed after the kill 
character to emphasize that the line will be deleted. Note that an escape character 
preceding the erase or kill character removes any special function. If ECHONL is set, 
the NL character will be echoed even if ECHO is not set. This is useful for terminals set 
to local echo (so-called half duplex). Unless escaped, the EOF character is not echoed. 
Because EOT is the default EOF character, this prevents terminals that respond to EOT 
from hanging up. 

If NOFLSH is set, the normal flush of the input and output queues associated with the 
quit, switch, and interrupt characters will not be done. 

The initial line -discipline control value is ISIG, ICANON, ECHO, ECNOE, ECHOK. 
The primary ioctl (2) system calls have the form: 

ioctl (fildes , command, arg) 

struct termio *arg; 

The commands using this form are: 



TCGETA 


Get the parameters associated with the terminal and store in the 
termio structure referenced by arg. 


TCSETA 


Set the parameters associated with the tenninal from the struc- 
ture referenced by arg. The change is immediate. 


TCSETAW 


Wait for the output to drain before setting the new parameters. 
This form should be used when changing parameters that will 
affect output. 


TCSETAF 


Wait for the output to drain, then flush the input queue and set 
the new parameters. 


Additional ioctl (2) calls have the form: 


ioctl {fildes , 
int arg\ 


command , arg) 


The commands using this form are: 


TCSBRK 


Wait for the output to drain. If arg is 0, then send a break (zero 
bits for 0.25 seconds). 


TCXONC 


Start/stop control. If arg is 0, suspend output; if 1, restart 
suspended output. 


TCFLSH 


If arg is 0, flush the input queue; if 1, flush the output queue; if 
2, flush both the input and output queues. 
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FILES 

/dev/tty* 

SEE ALSO 

stty(I) in Using Your SysV Environment. 

fork(2), ioctl(2), setpgrp(2), signal(2) in the SysV Programmer’ s Reference. 
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NAME 

timed - Transport Interface cooperating STREAMS module 
DESCRIPTION 

timed is a STREAMS module for use with the Transport Interface (TI) functions of the 
Network Services library. The timed module converts a set of ioctl(2) calls into 
STREAMS messages that may be consumed by a transport protocol provider which sup- 
ports the Transport Interface. This allows you to initiate certain TI functions as atomic 
operations. 

The timed module must be pushed (see Getting Started with SysV STREAMS ) onto a 
stream terminated by a transport protocol provider that supports the TI. 

All STREAMS messages, with the exception of the message types generated from the 
ioctl commands described below, are transparently passed to the neighboring 
STREAMS module or driver. The messages generated from the following ioctl com- 
mands are recognized and processed by the timed module. The format of the ioctl call 

is: 



#include <sys/stropts.h> 



struct strioctl strioctl; 



strioctl. ic_cmd = cmd; 
strioctl. ic_timeout = INFTIM; 
strioctl. ic_len = size; 
str ioctl. ic_dp = (char *)huf 

ioctl (JiUles, I_STR, &strioctl); 

Where: size is the size of the appropriate TI message to be sent to the transport provider 
and on return size is the size of the appropriate TI message from the transport provider 
in response to the issued TI message, huf is a pointer to a buffer large enough to hold 
the contents of the appropriate TI messages. TI message types are defined in 
<svs/tihdr.h>. Possible values for the and field are: 

TI_BIND Bind an address to the underlying transport protocol provider. The 

message issued to the TI_BIND ioctl is equivalent to the TI message 
type T_BIND_REQ and the message returned by the successful com- 
pletion of the ioctl is equivalent to the TI message type 
T_BIND_ACK. 
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TI_UNBIND Unbind an address from the underlying transport protocol provider. 

The message issued to the TMJNBIND ioctl is equivalent to the TI 
message type T_UNBIND_REQ and the message returned by the suc- 
cessful completion of the ioctl is equivalent to the TI message type 
T_OK_ACK. 

TI_GETINEO Get the TI protocol specific information from the transport protocol 
provider. The message issued to the TI_GETINFO ioctl is equivalent 
to the TI message type T_INFO_REQ and the message returned by the 
successful completion of the ioctl is equivalent to the TI message 
type T_INFO_ACK. 

TI_OPTMGMT Get, set or negotiate protocol specific options with the transport pro- 
tocol provider. The message issued to the TI_OPTMGMT ioctl is 
equivalent to the TI message type T_0 PTMG MT_REQ and the mes- 
sage returned by the successful completion of the ioctl is equivalent 
to the TI message type T_OPTMGMT_ACK. 

DIAGNOSTICS 

If the ioctl system call returns with a value greater than 0, the lower 8 bits of the return 
value are one of the TI error codes as defined in <sys/tiuser.h>. If the TI error is of 
type TSYSERR, the next 8 bits of the return value contain an error as defined in 
<sys/errno.h> (see intro(2)). 

FILES 

<sys/timod.h> 

<sys/tiuser.h> 

<svs/tihdr.h> 

<sy. s/err no. h> 

SEE ALSO 

tirdwr(7) 

Getting Started with SysV STREAMS 
Programming with SysV STREAMS 
Programming with the SysV Transport Interface 



10-32 



Special Files 




TIRDWR(7) 



SysV 



TERDWR(7) 



NAME 

tirdwr - Transport Interface read/write interface STREAMS module 
DESCRIPTION 

tirdwr is a STREAMS module that provides an alternate interface to a transport pro- 
vider which supports the Transport Interface (TI) functions of the Network Services 
library (see Section 3N). This alternate interface allows you to communicate with the 
transport protocol provider using the read(2) and vvrite(2) system calls. You can also 
use the putmsg(2) and getmsg(2) system calls, however, putmsg and getmsg can only 
transfer data messages between user and stream. 

The tirdwr module must only be pushed (see I_PUSH in streamio(7)) to a stream ter- 
minated by a transport protocol provider which supports the TI. After the tirdwr 
module has been pushed to a stream, none of the TI functions can be used. Subsequent 
calls to TI functions cause an error on the stream. Once the error is detected, system 
calls on the stream return an error with errno set to EPROTO. 

The following are the actions taken by the tirdwr module when pushed on the stream, 
popped (see I_POP in streamio(7)) off the stream, or when data passes through it. 

push - When the module is pushed to a stream, it checks your existing data to 
ensure that only regular data messages are present. It ignores any messages 
on the stream that relate to process management, such as messages that 
generate signals to your processes associated with the stream. If any other 
messages are present, the I_PUSH returns an error with errno set to 
EPROTO. 

write - The module takes the following actions on data that originated from a 
write system call: 

® All messages with the exception of messages that contain control por- 
tions (see the putmsg and getmsg system calls) are transparently 
passed to the module’s downstream neighbor. 

9 Any zero length data messages are freed by the module and are not 
passed to the module’s downstream neighbor. 

9 Any messages with control portions generate an error, and any further 
system calls associated with the stream fail with errno set to EPROTO. 

read - The module takes the following actions on data that originated from the 
transport protocol provider: 

9 All messages with the exception of those that contain control portions 
(see the putmsg and getmsg system calls) are transparently passed to 
the module’s upstream neighbor. 
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• The following action is taken on messages with control portions: 

Messages that represent expedited data generate an error. All 
further system calls associated with the stream fail with errno set 
to EPROTO. 



Any data messages with control portions have the control por- 
tions removed from the message prior to passing the message on 
to the upstream neighbor. 

Messages that represent an orderly release indication from the 
transport provider generate a zero length data message, indicating 
the end of file, which is sent to the reader of the stream. The ord- 
erly release message itself is freed by the module. 

Messages that represent an abortive disconnect indication from 
the transport provider cause all further write and putnisg system 
calls to fail with errno set to ENXIO. All further read and 
getnisg system calls return zero length data (indicating end of 
file) once all previous data has been read. 

With the exception of the above rules, all other messages with 
control portions generate an error and all further system calls 
associated with the stream fail with errno set to EPROTO. 



• Any zero length data messages are freed by the module and are not 
passed to the module’s upstream neighbor. 

pop - The module takes the following action when popping the module off or 

closing the stream: 

• If an orderly release indication has been previously received, an orderly 
release request is sent to the remote side of the transport connection. 

• If an abortive disconnect was previously received, no action is taken. 

• If neither an abortive disconnect nor an orderly release were previously 
received, the module initiates an abortive disconnect. 

• If an error occurred previously and an abortive disconnect was not pre- 
viously received, the module initiates an abortive disconnect. 



SEE ALSO 

streamio(7), timod(7) 

intro(2), getmsg(2), putmsg(2), read(2), write(2), intro(3) in the SysV Programmer' s 

Reference. 

Getting Started with SysV STREAMS 
Programming with SysV STREAMS 
Programming with the SysV Transport Interface 
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NAME 

tracem - STREAMS activity trace module 
DESCRIPTION 

tracem reports on messages passing through active Streams. You can insert instances 
of tracem at any point or points in one or more Streams, those instances then send 
copies of messages passing through them to another instance of tracem designated as a 
reporting module. 

trconf(l) inserts or removes tracing instances of tracem on a Stream. It also lists open 
Streams and the modules on them, and configures tracem modules to report on specific 
kinds of messages, trmon(l) opens a Stream to /dev/nuls, pushes a reporting instance 
of tracem onto that Stream, then prints (on standard output) messages sent to the 
reporting instance by tracing instance(s). 

FILES 

/dev/nuls 
SEE ALSO 

trmon(l), trconf(l), nuls(7), nulm(7) 
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NAME 

tty - controlling terminal interface 
DESCRIPTION 

The file /dev/tty is, in each process, a synonym for the control terminal associated with 
the process group of that process, if any. It is useful for programs or shell sequences 
that wish to be sure of writing messages on the terminal no matter how output has been 
redirected. It can also be used for programs that demand the name of a file for output, 
when typed output is desired and it is tiresome to find out what terminal is currently in 
use. 

FILES 

/dev/tty 

/dev/tty* 

SEE ALSO 

console(7), ports(7). 
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Using the netmain Interactive Tool 
and netmain_srvr in the Apollo 
Token Ring Network 



This appendix provides guidelines for using network topology lists and data gathered by 
netmain_srvr and the netmain interactive tool displays to draw conclusions about your 
Apollo Token Ring network’s performance. It contains methods to detect conditions that 
are potentially troublesome, and thus is oriented toward problem prevention. This appendix 
also contains information on routine maintenance to protect the physical integrity of your 
network. It includes information about 

• Node performance 

• Detecting intermittent network events 

• Problem isolation methods 

• Routine maintenance procedures 



A.1 Solving Network Problems with netmain and netmain_srvr 

This section provides step-by-step procedures that can help you to start using the netmain 
menus. These procedures show you how to move through the menus and perform some of 
the basic operations needed to control netmainjsrvr. Refer to later sections for a full de- 
scription of the netmain interactive tool menus and the netmain__srvr options. 



A. 1.1 Starting and Stopping the netmainjsrvr 

To start the netmain_srvr, use one of the methods described below. 
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Starting netmainjsrvr from the DM Command Line 
To start the netmain_srvr from the DM command line, type: 

Command: /etc/server netmainjsrvr [-options] 

The server process begins immediately and continues after logout. 



Starting the netmainjsrvr from a Start-Up File 

To automatically start netmainjSrvr server, uncomment the following lines in the disked 
node’s /etc/rc.user file. 

#i£ [ -f /sys/net/netmain_srvr ] ; then 

# (echo " netmain_srvr\c" >/dev/console) 

# /sys/net/netmain__srvr & 

#fi 

The server process begins when the node comes online and continues after logout. If you 
don’t wish to use the entire set of defaults, you can specify those you wish to use with op- 
tions in the netmainjSrvr command line or configuration file. See Section A. 4 for details 
on options. 



Stopping the netmainjSrvr 

When started by the methods described above, netmainjSrvr continues running until it is 
intentionally stopped with either of the following commands: 

$ kill netmaiHjSrvr -q (UNIX operating system environments) 

$ sigp netmain_srvr ~q (Aegis operating system environment) 

The server process stops running if the node is shut down intentionally or if the system 
crashes. If the process stops running, you may start it from the DM command line or by 
rebooting the node. 

A. 1.2 Getting Started with netmainjsrvr and netmain 

Before you can practice using netmain, a monitor has to run in your network. If no moni- 
tors are running in your network, start netmainjSrvr as described above. Let the monitor 
run, with default values, for a week. Then you may begin Procedure A-2. If you already 
have had netmainjSrvr running for more than a week, proceed directly to Procedure A-2. 
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Procedure A-2 Getting Started with Netmain 



Task 1: Invoke netmain. 

To invoke netmain, type: 

$ netmain -whelp 

The -whelp option tells netmain to grow the window, to display the entire netmain 
menu, including the help area. The Top-Level menu, the top of which is shown be- 
low, appears. 




Task 2: Study the menu. 

The menu name appears in the top-left corner. 

Each command box, across the top of the menu, shows a command and the key- 
board function keys, FI through F8. 

Netmain messages that describe functions selected appear below the command boxes. 
The message, “No monitors are known,” below the command boxes reminds you that 
you haven’t yet chosen a monitor. Netmain also uses this area to draw an input box 
and to prompt you for input. 

Error and status messages appear above the command boxes. Netmain reports on its 
activity as it carries out commands. There are no messages above the command box 
right now. A “Topology List status” message appears in the top right corner. 
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The large box at the bottom of the screen contains online help about each menu. 



Task 3: 

Taks 4: 
Task 5: 



Task 6: 



Task 7: 
Task 8: 



Locate the + shaped cursor in the netmain window. 

Use the arrow keys, touch-pad, mouse, or bitpad to move the cursor. Move the cur- 
sor outside the window. It regains its rectangular shape and the Display Manager is in 
control. Move the cursor back to the netmain window. 



Point to a command box by placing the cursor in the box. 

Notice that pointing to a command box accents the box. It changes color. When a 
box is accented, the + shaped cursor is no longer visible. 



Point to the “F6 Shrink window to icon” command box to make the netmain win- 
dow into an icon. 

To get help on any netmain command or parameter, type h, or ?, or press the mid- 
dle or right buttons on the mouse, or press any button except the top on the bit-pad 
puck. The menu help box displays additional information about the command. 

Select the “F6 Shrink window to icon” command. 

To select a box in a netmain menu, you can use one of the following methods: 

• Press the appropriate function key (only for command boxes labeled with func- 
tion key names). 

• Point to the box and press the keyboard’s space bar. 

• Point to the box and press the mouse’s left button. 

• Point to the box and press the top button of the bit-pad puck. 

The netmain window becomes an icon. The netmain program continues to run in the 

icon, retaining any information it has amassed, but taking up little space on the 
screen. 



Point to the netmain icon by moving the DM cursor over the icon. 

Request help about the icon by pointing to it and typing h or ?, pressing the mid 
die or right button on the mouse, or pressing any button except the top one on 
the bit-pad puck. 

A system help file is displayed. 
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Task 9: Enter netmain by pointing to the icon and pressing the space bar. Then select 

“F2 Change monitor behavior.” 

Note the error message that appears. You have not yet selected a monitor with which 
to work. 

Task 10: Now look for the command box to exit from netmain. 

As you probably guessed, it’s the F8 Exit box. On any netmain menu, use this com- 
mand box to exit to the higher-level menu. On this top menu, use it to exit from 
netmain. 



A. 1.3 Establishing Network Performance Levels 

If users perceive poor network performance, use the information netmain_srvr gathers to 
determine the reason. Sometimes a small or intermittent problem in a connector, cable, or 
ring interface board can cause network or node performance problems. This section de- 
scribes how to use the netmain interactive tool to look for such problems and isolate them 
to one point in the network, usually a node’s IN and OUT cables and connectors. Some- 
times poor distribution of network resources can also cause poor network performance. 

This section describes how to “tune” the network by searching for subtle problems that can 
affect performance. Follow the suggestions in this section to prevent problems and enhance 
network performance. Section A. 5 describes how to use the netmain interactive tool to 
detect resource distribution problems. 

To increase your understanding of the material in this appendix, use the netmain interac- 
tive tool and perform the operations described as you read the material. Allow ample time 
to cover the material, and keep your reading and practice sessions short. 



Evaluating Node Performance 

The netmain interactive tool displays can be used to analyze individual node performance 
as well as overall network performance. This section describes how to use these displays to 
evaluate the performance of individual nodes in the network. Questions that require an 
evaluation of node performance include the following: 

o What percentage of network resources are provided by individual nodes, and is 
this distribution appropriate for the network? 

o Are nodes’ diskless partner assignments affecting the performance of either node? 

o Is any node experiencing a high number of disk or memory errors that could indi- 
cate hardware problems? 
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Locating Underused or Overused Nodes 

The CPU_TIME and NET_SERVICE probes gather data about CPU usage and network 
requests. The categories CPU SERVICE and QUEUE SERVICE from the netmain interac- 
tive tool’s Analyze Network Data menu include performance statistics for data gathered by 
these probes. To locate underused or overused nodes, look at performance statistics in 
these categories. Also, use the output formats that report on diskless nodes. This section 
provides guidelines for using these tools. 

Look at the network resources that nodes provide by checking the number of diskless part- 
ners assigned to each node. Choose the “Diskless partners” output format and select “Part- 
ners, by mother.” Check the number of diskless partners assigned to the nodes shown. If 
some nodes have several diskless partners and others have none, consider reassigning some 
diskless nodes to other partners. If the nodes are servers, dedicated to serving diskless 
node, the arrangement may be satisfactory. 

Next, choose a “Density across network” output format. It shows each node’s relative con- 
* tribution of a resource as a percentage of the total for the network. Start by looking at the 
“Total file service” and “Total page service” performance statistics. These statistics show 
the number of file services and paging services each node performs for other nodes. A 
node provides these services when other nodes need to read, write, open, close, and list its 
files. Nodes with diskless partners have higher counts of these services than nodes without 
diskless partners. Experiment by setting the “top of error scale” level in the Parameter 
menu to different values. In the output displays, look for the following patterns: 

• Sharp, high-density, vertical lines underneath certain nodes, extending across all 
time intervals 

• Sharp, high-density, vertical lines that appear only during certain time intervals 

A node with a high-density vertical line is heavily consuming the network resource shown 
by that performance statistic. Check to see whether such heavily used nodes are servers 
nodes (typically DSPs, such as the DSP90 or DSP160), and/or whether they have diskless 
partners (use the ” Diskless partners” format). 

If a heavily used node has no diskless partners and isn’t a server node, it may contain a 
system resource that can be replicated elsewhere. For example, if commonly used sets of 
files can be replicated on other nodes, the traffic at this node will be lighter. Note, how- 
ever, that files are good candidates for replication only if there is a mechanism for coordi- 
nating file updates. If a node is heavily used only at certain times (a high-density line ap- 
pears at certain time intervals, then fades), investigate the activity on that node during 
these times. 

If only servers and/or partners of diskless nodes are used heavily, check the relative contri- 
bution of each server. Create a data file containing only the names of the servers. Use the 
format described in Section A.5 for the F5 (Topo list from data file) command in the 
Find Monitors and Nodes menu. Put the data file in the topology list. Then use the “Den- 
sity across network” format to look at the performance statistics again. 
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Look for high-density vertical lines that indicate heavy loads on individual nodes and also 
look for high-density horizontal bands. High-density bands can give information about 
times of peak use in the network. Analyze user activities during these peak periods to de- 
termine which activities consume system resources. You may be able to change the “mix” 
of services on the server nodes to create a more efficient pattern of use. 

Use rates or incidence formats to analyze nodes* file and paging services performed for 
other nodes. To find out about a node’s performance during times of peak use, display 
“page or file backlog severity” performance statistics (from the QUEUE_SERVICE cate- 
gory). Backlog severity statistics report the average number of service requests in the file or 
paging service queues, at times when there are requests in these queues. 

These statistics show the nodes that are most heavily used during peak periods. Traffic in 
local area networks tends to occur in bursts, and distributing resources to share the load 
during peak periods can help to provide maximum performance of your network. To com- 
pare the contributions of individual nodes, use an across-network display format. 

The “any backlog” statistic shows all unserviced requests in a service queue. The “average 
backlog” statistic shows the average number of requests in a queue over time. Note that a 
high average backlog or backlog severity level is not an error condition. It shows that the 
node is providing a relatively high percentage of service to the network. Evaluating this 
condition depends on what you intend the node to provide, and what you intend other 
nodes to provide. 

If an “any backlog” display shows that some nodes have backlogs and others do not, dis- 
tribute more resources to nodes without backlogs. If some nodes have a higher average 
queue length than others, investigate the number of pages of memory that node has allot- 
ted for paging requests from remote nodes. If a user has used the netsvc shell command 
with the -p[rc] option, remote nodes are limited to only n pages of the node’s memory, 
and this could add slightly to the queue length. 

For more information when you suspect a node is overused, look at the “Total disk activ- 
ity” performance statistic from the DISK category. Display the data by using the same rates 
or incidence formats that you used with the CPU SERVICE and QUEUE SERVICE data. 
Use the Display Manager (DM) to place one output pad directly over the other. If both 
displays show a vertical high-density line for the node in question, it is probably overused. 
To confirm this, compare this node’s DISK category statistic with those of other nodes in . 
the network. If this node’s disk activity is comparable to that of other nodes, it is not, in 
fact, being overused. 

The procedures described above are used to search for nodes that are providing more than 
their share of network resources. To find nodes that are providing less than their share, 
use the “Null CPU time” performance statistic in various display formats. Density formats 
are useful because they allow you to easily compare node’s performance. 

All nodes have some percentage of Null CPU time. Compare the node’s “Null CPU” time 
to its “Total disk activity” from the DISK category, using the “two-display” technique de- 
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scribed earlier. If the node shows both a high disk activity level and a high Null CPU time 
level, the node may be spending too much time servicing paging requests and not enough 
time using the CPU for computation. The node’s performance might improve if it were 
used less as a system resource. 

Nodes that show high “Null CPU” time but do not have a high “Total disk activity” level 
can provide more network services. Nodes without service queue backlogs can also provide 
more network services. Use a “peaks” format to look for nodes with no service queue 
backlogs. 



Diskless Partner Information 

The previous subsection described a quick check to compare diskless partner assignments 
for nodes of various types. Use the network resource analysis techniques described in this 
subsection to ensure that nodes are not acting as partners to too many diskless nodes. 

To ensure that diskless nodes’ partners are in the same network loop, prepare data files 
with lists of nodes in each network loop. Put the data files into the Topo List (F5 in the 
Find Monitors and Nodes menu). Then use the “Diskless partners” output format to dis- 
play diskless nodes and their partner nodes. Verify that each diskless node has a partner in 
the same loop. 



Disk and Memory Errors 

Performance statistics in the DISK and STORAGE MODULE categories, and printed dis- 
plays on memory errors can alert you to potential hardware problems. In the DISK and 
STORAGE MODULE categories, use any graph display format, particularly a peaks for- 
mat, to check for Disk or SMD (Storage Module Disk) CRC error. Set the “top of error 
scale” to 5%. If a disk or SMD shows high or increasing levels of CRC errors (above 
0.01%), copy user files elsewhere and contact a service representative. Incidences of 
“Disk/SMD not ready” or “Disk equipment check” conditions also should not occur. 

In printed displays of memory errors .look for sudden occurrences of ECCC or ECCU er- 
rors. If these occur, contact a service representative. In the case of ECCC errors, the serv- 
ice representative can determine if there actually is a problem. In the case of ECCU er- 
rors, a hardware problem is usually indicated. The service representative may replace a 
failing board. 

A.2 Detecting Unusual or Intermittent Network Events 

Use the methods described below to find intermittent or unusual network performance con- 
ditions and to recognize these conditions in netmain tool displays. 

Become familiar with the performance levels typical of your network. Do this by producing 
plots via the “incidence density output” format. Choose performance statistics in the RING 
RECEIVE or RING TRANSMIT categories. Look for horizontal high-density bands ex- 
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tending across all nodes in the network for a period of time. These high-density bands in- 
dicate that the entire network showed increased levels of the performance statistic you are 
analyzing, over a certain time period. 

Compare the times at which horizontal high-density bands appear on plots for different 
days. If there is any pattern to the time periods, investigate user and network activities oc- 
curring during these time periods. 

When you start to look for intermittent conditions, check two performance statistics in the 
RING TRANSMIT category, “Transmit no return” and “Transmit packet error,” for levels 
that rise across the entire network during any kind of a problem. 

Select “Transmit no return” and an incidence density format to display the data. Set the 
“top of error scale” to 25%. If most of the nodes in the network show some gray, there 
may be a problem worth investigating further. Increased levels of this statistic occur when 
nodes send a packet but do not get a response in return. High levels for this statistic can 
indicate a cable or connector problem. Cable or connector problems can cause nodes to 
send hardware failure messages. Select a “Scattergram events output” format and look at 
hardware failure messages. Note the nodes that report hardware failure messages. Check 
the cables and connectors for these nodes and for nodes directly upstream of them. 

If there are no hardware failure messages in the scattergram, or if the “Transmit no re- 
turn” statistics did not indicate problems, look at the “Transmit packet error” performance 
statistic. Choose an “incidence density” format to display the data. Leave the “top of error 
percentage scale” at its default value of 50%. If most of the nodes in the network don’t 
show much gray, there is probably not a problem. If most do show gray, choose an “inci- 
dence peaks” format and experiment with various “Top of error threshold scale” levels. 
Note the level at which many nodes start to show peaks of “Transmit packet errors.” Also 
note whether the peaks occur for most nodes or only some nodes. 



Isolating a Problem to a Particular Node 

This subsection describes how to look at displays of performance statistics to isolate the 
source of the problems described in the previous subsections. 

Choose an “incidence density” format and any of the following performance statistics: 

© Receive modem errors (from RING RECEIVE category) 

© Receive biphase errors (from RING RECEIVE category) 

® Transmit modem errors (from RING TRANSMIT category) 

© Transmit biphase errors (from RING TRANSMIT category) 

In the displays, look for a vertical, sharp, high-density line under one node. It indicates 
saturation or near-saturation conditions for that node. If you don’t see a high-density line 
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under any node in the gray scale plot, lower the “top of error scale” and see if the condi- 
tion occurs. Figure A-2 shows an example of such a condition in a density plot. 

If the output shows a high-density vertical line, inspect that node, the node immediately 
upstream, and all the cables and connections between these nodes. This output can indi- 
cate a problem in the node’s ring interface hardware that is not affecting other nodes in 
the network, but sometimes it can point out a problem with cabling or a connection. 

Check further by examining output from an active monitor while someone moves the ca- 
bles in the areas that you suspect. If the count increases, the problem is probably in the 
physical medium (cables or connectors) . 



Incidence of "Rev CRC' among "Network receives" 

Data taken from log file //THE_HEDGE/NET_DISPL A YS/NETLOC | 
Scale saturates at 1Z incidence. 



Source of node list: 

LCBODE froa monitor on RODE 8FC5 
logged at 23:31, 7 January 1984 

in log file //THE-^EKZ/JfZT. J> I SPLAYS/EET- LDG.84.il. 86 
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Figure A-2. High-Density Line Condition 
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If moving the cables does not affect the density, the problem may be in the ring interface 
hardware for the node that showed the high-density vertical line, or the ring hardware of 
the node upstream. Use the shell command netsvc -n to take one of the nodes off the 
network while you continue to examine output from an active monitor. If the high-density 
vertical line starts to disappear, the problem is probably in the node that you removed 
from the network. While the node is off the network, see if “Transmit packet error” levels 
go down significantly. If the results show that the node is hindering network performance, 
schedule maintenance for the node. 

Choose an “incidence density” format, and the “Rev CRC” performance statistic in the 
RING RECEIVE category. The operating system increments counts for this statistic when 
part of a received message does not pass the CRC. Thus, this statistic correlates with cor- 
ruption of one or several bits in a packet. 

Set the “Top of error percentage scale” to 1%. Look for areas of high density that fade 
horizontally into areas of lower density. Figure A-3 shows an example of high-density fade 
in a gray scale plot. 
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Figure A-3. High-Density Fade Condition 

High-density areas that fade into low-density areas indicate a problem in one node that* 
affects data integrity in other nodes. The nodes with the highest density are closest to the 
problem because almost all the messages they receive must pass through the node causing 
the problem. Nodes that are further downstream show a lower error density because they 
receive some messages that haven’t passed through the node causing a problem. 

If you do not detect the condition, set the “Top of error scale” lower. The high-to-low 
density fade condition can be seen more readily in larger networks since many more nodes 
are sampled. If you detect the condition, put the output pad for the plot near the bottom 
of the screen. Then request another incidence density display for the “Transmit modem 
error” performance statistic. Set the plot resolution to the same level you used for the 
“Rev CRC error” performance statistic. Move the second output pad so that its columns 
line up with the first. Look at the node at which the high-density fade begins in the “Rev 
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crc” plot. Check for a high-density vertical line located under the same node in the “mo- 
dem error” plot. In this situation, the node is producing modem errors, which corrupts 
data in nodes downstream. However, the further away a node is from the problem node, 
the fewer of its received messages must pass through the problem node, so the lower its 
percentage of corrupted data. The increasingly lower percentages produce the fade effect. 
Figure A-4 shows two plots aligned in just this manner. 

If you isolate a problem node by aligning plots, investigate the node, the node upstream, 
and their cables and connectors very thoroughly. Use this technique with “Density across 
network” plots as well as incidence density plots. In addition, look for density fade condi- 
tions for “Rev ack parity” and “Rev header checksum” performance statistics. 




Figure A-4. Aligned Plots 
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More Intensive Methods of Locating Network Performance Problems 

If you want more information about a node than is provided by the methods described 
previously, activate the SWD_10_MSGS or SWD_100_MSGS probe on a monitor in the 
network. These probes record performance statistic levels before and after transmission of 
a set of messages to each node. The SW DIAGNOSTIC (SWD) category includes many of 
the performance statistics that are in the RING RECEIVE category, but the counts dis- 
played are only about packets sent by SWD messages. 

To analyze SWD performance statistics, use the techniques described in the preceding sec- 
tions. Be aware, however, that these probes can significantly add to network traffic. Use 
them to get information unobtainable by other means. 

A.3 The Network Log Book 

Keep a network log book, containing the information collected from netmain_srvr, online 
or as a hard copy. In it, store files produced from the netmain interactive tool displays 
and other relevant network information. Record the date and time that new nodes are in- 
stalled in the network, and identify the nodes that run network services. 

Include in the log book the following information about network problems: 

• Date and time the problem was detected (essential in tracking network problems 
and helpful in interpreting the information gathered by netmain_srvr) 

• Name of person who discovered and/or debugged the network problem 

• The node that reported a ring hardware error, if any, or from the netmain inter- 
active tool’s Analyze Network Data menu 

• The netmain interactive tool analysis information that relates to the problem 

• Action taken to restore the network, if necessary 

Write supplemental notes to netmain_srvr log files. Include information about scheduled 
service time, new node installations, and problem occurrences. Write notes in two ways: 

• With the netmain interactive tool, use the “F4 Log a text string” command box 
in the Change Monitor Behavior menu. 

• Outside the netmain interactive environment, use the netmain_note command, as 
shown below. 
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Type: 



$ /com/netmainjnote message 
For example, you might type: 

$ /com/netmain_note Loop 17 scheduled downtime 

To retrieve the notes stored in a log file, use the “Printed Output” format in the netmain 
interactive tool’s Analyze Network Data menu. 



A.4 The netmaim_srvr Reference 

The netmain_srvr (/sys/net/netmain_srvr) program collects data used for maintaining the 
Apollo Token Ring network. Use the data for monitoring ring performance and isolating 
potential problems. Use the netmain interactive tool, described in Section A. 5, to interact 
with netmain_srvr. 

The netmainsrvr process running on any node is called the node’s monitor. Monitors 
execute subprograms called “probes” and “observers”, which are usually in a waiting state. 
At specified intervals, each probe becomes active and collects some data about nodes in 
the ring. The probe stores the information it collects in non-ASCII files called “log” files, 
then returns to its waiting state. 

Each time a probe gathers data, an observer sifts through it to detect either a transmit mo- 
dem error (MODEM_ERRS) or a disk drive error (WIN_CRC). If an observer detects 
either condition, it can provide an alarm on the node running a monitor. 

The netmain_srvr’s probe and observer log files on active monitors are open. You cannot 
analyze the information in them until you close them with the netmain interactive tool. 

Log files reside in the ‘node_data/system_logs/net_log directory by default. 

If netmain_srvr does not start properly, a record of the failure appears in the file 
‘node_data/system_logs/netmain_srvr.err.log. If you experience problems starting net- 
main__srvr or if the monitor dies, use the data in the error log to determine the cause of 
the problem. The netmain_srvr error logs are ASCII files, and you can treat them as you 
would treat any ASCII file. 

There are two shell commands that can help you manage netmain_srvr logs. The first, 
netmain__chklog, checks for and, if appropriate, deletes corrupted netmain_srvr log files. 
Use netmain_chklog if a node running netmain__srvr crashes or is reset (via the RESET 
switch or button) . The log file that netmain_srvr was writing when the node crashed will 
be corrupted. Delete it with netmain__chklog. Attempts to analyze data from a corrupted 
log file may cause netmain to behave unpredictably. 
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Use the netmain_note shell command when you are outside of the netmain interactive 
tool environment and want to send a text string to a netmain_srvr log file. The Command 
Reference manual for any of the three environments provides information on 
netmain_chklog and netmain_note. 



A.4.1 Invoking netmainjsrvr 

The netmainjsrvr process should run as a background process from the etc/rc file. By 
default, the process names itself netmain_srvr, so you need not use the -n option with the 
process creation command. Run monitors only on nodes with disks, not on diskless nodes 
or Domain Server Processors (DSP)s. Whenever possible, run a monitor in each loop so 
that data can be collected even if the loop is switched out of the main ring. Ensure that 
monitors are configured so that they collect the data you need, without creating log files 
that take up too much disk space, and without affecting performance of the nodes on 
which the monitors run. 

Online help for instructions on controlling netmainjSrvr after it starts, and on analyzing 
the data collected is available by typing 



$ /com/help netmain 

For information about adding notes to the network error log, type 



$ /com/help netmain_note 

For information about detecting and deleting corrupt log files, type 



$ /com/help netmain_chklog 

To start netmain_srvr from the DM command line, type 

Command: /etc/server netmainjsrvr [-options] 

The process begins immediately and continues after logout. 
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To automatically start the server, uncomment the following four lines in the disked node’s 
etc/rc.user file. 

#if [ -f /sys/net/netmain_srvr ] ; then 

# (echo " netmain srvr\c" >/dev/console) 

# /sys/net/netmain_srvr & 

#fi 

The process begins when the node comes online and continues after logout. If you don’t 
wish to use the entire set of defaults for a monitor, you can specify those you wish to use 
with options in the netmain __srvr command line or configuration file. 

When started by the methods described above, netmain__srvr continues running until it is 
intentionally stopped with either of the following shell commands: 

$ kill netmain_srvr -q (UNIX operating system environments) 

$ sigp netmain_srvr -q (Aegis operating system environment) 

The process stops running if the node is shut down intentionally or if the system crashes. If 
the process stops running, you may start it from the DM command line or by rebooting the 
node. 



Options and Arguments 

The netmain_srvr process has a number of options. Instead of including them all on the 
command line you can use an options file by specifying the -c[mdf] option. If you spec- 
ify -c pathname, the server first reads the options listed in the options file specified, and 
then reads any other options on the netmain_srvr command line. If there are any con- 
flicts between the options file and the command line, the command line settings are used. 
For example, if the options file specifies -11 1500 and the command line specifies -11 
3000, 3000 is the limit on the log file’s length. 

Default options are indicated by (D) . 

-a[ppend] Appends to an existing log file the name specified by the -1 option; 

otherwise, creates a log file with this name. This option is only valid 
when a log file pathname is specified with the -1 option. Contrast 
this with the -nappend option. 



-c[mdf] [pathname] 

Accepts options from an ASCII text file pathname. You may use this 
option only from the command line, not in the options file. There 
can only be one options file. 

-l[og] [pathname ] (D) 

Creates a log file. Optionally, this specifies a pathname, which is rela- 
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tive to the 4 node__data/system_logs/net_Jog directory. If either this 
option or the pathname is not specified, the log filename is derived 
from the current date: ‘node_data/system_logs/net_log/net_ 
log.yy.mm.dd. The log file is stored on the disk of the node running 
netmain_srvr and must remain there for netmain__srvr to write to it. 

A.4.2 Data Collected by netmain_srvr Probes and Observers 

The following list describes the data collected by the probes and observers run by net- 
main_srvr monitors. The descriptions of items sometimes refer to “output formats,” or 
“display formats.” Generate these formats with the netmain interactive tool. 



CPUJTIME - Null/AEGIS/user CPU Time 

The CPU_TIME probe records performance statistics about each node’s CPU usage and 
writes them to 4 node_data/system_Iogs/net_log/net__log.yy.mm.dd or a file you specify. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 



Aegis CPU time: Shows the time the operating system on each node spends on internal 

needs, and on servicing requests from other nodes. Expressed as a 
percentage of elapsed time. This statistic does not show the time the 
operating system spends servicing calls from user programs, running 
server programs, or running the Display Manager. 



Null CPU time: Shows the time each node’s CPU is idle, as a percentage of elapsed 

time. Idle CPU time is any time during which the CPU is not perform- 
ing computations. Expect all nodes to show a certain amount of idle 
time, for time spent servicing page faults, etc. If a node shows both a 
high disk activity level and a high CPU time level, it may be spending 
too much time servicing page faults (thrashing) . 

User CPU time: Shows, as a percentage of elapsed time, the time the CPU on each 

node spends running user programs, shell programs, the Display Man- 
ager, and server processes. The statistic does not currently show the 
time used by individual processes or programs. 



DISKJERRS - Disk and Storage Module Errors 

The DISK_ERROR probe records cumulative information about disk and storage module 
performance and errors on all nodes and writes them to 4 node_data/system_logs/net_log/ 
net_log.yy.mm.dd or a file you specify. 

Default Probe Interval Time: 0:30:00 
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Default Probe Skip Distance: 1 



Controller busy: Counts the number of requests for disk I/O that could not be serviced 

because the controller was busy. On storage modules, only data for 
Unit 0 is recorded. The display formats show the statistic as a percent- 
age of the disk’s total I/O. 

CRC errors: Counts Cyclic Redundancy Check (CRC) errors on the storage device. 

On storage modules, only data for Unit 0 is recorded. The display for- 
mats show the statistic as a percentage of the disk’s total I/O. 

Disk reads as percentage of disk I/O: 

Calculates the ratio of reads to the node’s total Winchester disk I/O. 
The performance statistic is shown as a percentage of the node’s total 
Winchester I/O. If the count for this statistic is 49 percent, for exam- 
ple, reads account for 49 percent of all the node’s Winchester I/O. 

Disk writes as percentage of disk I/O: 

Calculates the ratio of writes to the node’s total Winchester disk I/O. 
The performance statistic is shown as a percentage of the node’s total 
Winchester I/O. If the count for this statistic is 51 percent, for exam- 
ple, writes account for 51 percent of all the node’s Winchester I/O. 

Equipment check: Counts the number of device equipment checks that occur. Problems 

on the device controller, such as controller memory component errors, 
internal micro-diagnostic failures, or internal timing problems, can 
cause equipment checks. On storage modules, only data for Unit 0 is 
recorded. The display formats show the statistic as a percentage of the 
disk’s total I/O. 

Counts the number of times that a “disk not ready” error condition 
occurs on a disk. On storage modules, only data for Unit 0 is re- 
corded. The display formats show the statistic as a percentage of the 
disk’s total I/O. 

Counts Direct Memory Access (DMA) overruns on the storage device. 
On storage modules, only data for Unit 0 is recorded. The display for- 
mats show the statistic as a percentage of the disk’s total I/O. 

Counts the number of attempts to find a track that occur on the stor- 
age device. On storage modules, only data for Unit 0 is recorded. The 
display formats show the statistic as a percentage of the disk’s total 
I/O. 

Storage module reads as percentage of storage module I/O: 

Shows the ratio of storage module reads to the node’s total storage 
module I/O. The performance statistic is shown as a percentage of the 
node’s total storage module I/O. If the count for this statistic is 51 
percent, for example, reads account for 51 percent of all the storage 



Not ready: 



Overruns: 



Seek error: 
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module’s I/O. Only data for the first storage module (Unit 0) is dis- 
played. Counts are expressed as a percentage of the device’s I/O. 

Storage module writes as percentage of storage module I/O: 

Shows the ratio of storage module writes to the node’s total storage 
module I/O. The performance statistic is shown as a percentage of the 
node’s total storage module I/O. If the count for this statistic is 51 
percent, for example, writes account for 51 percent of all the storage 
module’s I/O. Only data for the first storage module (Unit 0) is dis- 
played. 

Timeouts: Counts the number of controller timeouts on the storage device. On 

storage modules, only data for Unit 0 is recorded. The display formats 
show the statistic as a percentage of the disk’s total I/O. 

Total storage module activity: 

Measures the total disk storage module activity (reads plus writes) of 
each node (always 0 for nodes without storage modules). Use this per- 
formance statistic only with plots of network totals or rates from the 
netmain interactive tool. Shows the disk activity per node as a per- 
centage of the total Winchester disk activity for the entire network, or 
absolute I/O rates per unit time. Only data for the first storage module 
(unit 0) is displayed. 

Total Winchester disk activity: 

Measures the total Winchester disk activity (reads plus writes) of each 
node. Use this performance statistic only with plots of network totals 
or rates from the netmain interactive tool. Shows the disk activity per 
node as a percentage of the total Winchester disk activity for the en- 
tire network, or absolute I/O rates per unit time. 



ERR_COUNTS - Network Error Counts (Normal Traffic) 

The ERROR_COUNTS probe records cumulative network performance statistics and error 
counts on all nodes and writes them to ‘node_data/system_logs/net_log/net__log.yy.m 
m.dd or a file you specify. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 

Acknowledge, negative (NACK): 

Counts the number of transmissions in which the destination node did 
not acknowledge receipt of the message. NACKs can occur when 
nodes send messages to a node whose loop is switched out of the net- 
work, or a node that is not running the operating system. Expect 
large numbers of NACKs on nodes running netmain_srvr. The display 
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formats show the statistic as a percentage of the node’s total network 
transmits. 

Acknowledge parity, receive (ACK): 

Counts the number of parity errors in the hardware protocol segments 
of received messages. The hardware always detects ACK parity errors 
if any occur. The display formats show the statistic as a percentage of 
the node’s total network receives. 

Acknowledge parity, transmit (ACK): 

Counts the number of parity errors in the hardware protocol segments 
of transmitted messages. The hardware always detects ACK parity 
errors if any occur. The display formats show the statistic as a percent- 
age of the node’s total network transmits. 

Acknowledge, Wait (WACK): 

Counts the number of times that the destination node was too busy to 
accept a message in the time allotted. This performance statistic does 
not necessarily reflect an error condition — on a DN4xx/DN6xx 
nodes, for example, the node may have been performing disk I/O us- 
ing the shared ring/disk hardware. The display formats show the statis- 
tic as a percentage of the node’s total network transmits. 

Biphase error, receive: 

Counts the number of biphase errors that occur. Biphase errors occur 
when a node’s modem hardware cannot lock on the transmission fre- 
quency from the node upstream. Biphase errors can result from mo- 
dem hardware failures, broken cables or connectors, or signal degrada- 
tion caused by excessive cable lengths between active nodes. The dis- 
play formats show the statistic as a percentage of the node’s total net- 
work receives. The ERR_COUNTS probe collects data for this statistic 
only from nodes running SR8 or later releases. 

Biphase error, transmit: 

Counts the number of biphase errors that occur. Biphase errors occur 
when a node’s modem hardware cannot lock on the transmission fre- 
quency from the node upstream. Biphase errors can result from mo- 
dem hardware failures, broken cables or connectors, or signal degrada- 
tion caused by excessive cable lengths between active nodes. The dis- 
play formats show the statistic as a percentage of the node’s total net- 
work transmits. The ERR_COUNTS probe collects data for this per- 
formance statistic, only from nodes running SR8 or later releases. 

Bus error, receive: Counts errors during Direct Memory Access (DMA) from the ring 
controller. The display formats show the statistic as a percentage of 
the node’s total network receives. 
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Bus error, transmit: 



Counts the number of times that the ring controller experienced a bus 
error during a Direct Memory Access (DMA) transfer. The display 
formats show the statistic as a percentage of the node’s total network 
transmits. 

CRC, receive: Counts messages that contain Cyclical Redundancy Check (CRC) er- 

rors, detected by the ring hardware. CRC errors can result from er- 
rors in any part of the received message, except the hardware protocol 
segments. You cannot disable CRC checking. Compare CRC error 
statistics to those for RCV header checksum and ACK parity errors. 
The display formats show the statistic as a percentage of the node’s 
total network transmits. 

End-of-range, receive: 

Counts the number of times that one or both of the message fields in 
the packet received was larger than the Direct Memory Access (DMA) 
channel allowed for it. The display formats show the statistic as a per- 
centage of the node’s total network receives. 



ESB errors, receive: 

Counts the number of elastic store buffer errors received. These errors 
arise when the node cannot follow a large or sudden change in the 
network communication frequency. The display formats show the sta- 
tistic as a percentage of the node’s total network receives. The 
ERR_COUNTS probe collects data for this statistic only from nodes 
running SR8 or later releases. 

ESB errors, transmit: 

Counts the number of Elastic Store Buffer (ESB) errors that occur. 
ESB errors occur when the node is unable to follow a large or sudden 
change in the network’s communication frequency. The display for- 
mats show the statistic as a percentage of the node’s total network 
transmits. The ERR_COUNTS probe collects data for this statistic, 
only from nodes running SR8 or later releases. 

Header checksum, receive: 

Counts messages that contain checksum errors in the message header. 
Since the operating system program that verifies header checksums is 
usually disabled, the count for this statistic should be 0. The display 
formats show the statistic as a percentage of the node’s total network 
receives. 

Modem error, receive: 

Counts the number of times the receiver could not synchronize prop- 
erly with the network. The conditions that cause this error are 
biphase or Elastic Store Buffer (ESB) errors. See the “receive biphase 
error” or “receive ESB error” statistics. The display formats show the 
statistic as a percentage of the node’s total network receives. 
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Modem error, transmit: 

Counts the number of times the transmitter could not synchronize 
properly with the network, resulting in an Xmit ESB or biphase error 
condition. See “transmit biphase errors” and “transmit ESB errors.” 

If the error condition lasts more than one minute, the node broadcasts 
a “hardware failure report” (displayed in the nodestat shell command 
output). A broken cable can cause modem errors. The display for- 
mats show the statistic as a percentage of the node’s total network 
transmits. 

No return, transmit: 

Counts the number of transmitted messages that failed to return to the 
node. After a destination node receives and copies a message, the 
message continues to travel around the ring until it returns to its trans- 
mitter, which removes the message. If a message does not return, it 
could not complete the loop around the ring, indicating a break in the 
ring. The display formats show the statistic as a percentage of the 
node’s total network transmits. 

Overrun, receive: Counts the number of Direct Memory Access (DMA) overruns that 

occur. The display formats show the statistic as a percentage of the 
node’s total network receives. 

Overrun, transmit: Counts the number of times that the ring controller experienced a Di- 

rect Memory Access (DMA) overrun condition during a ring transmit. 
The display formats show the statistic as a percentage of the node’s 
total network transmits. 

Packet error, receive: 

Counts the number of times either the receiver or the transmitter had 
problems with messages. If the fault was in the receiver, other counts 
are incremented also. The display formats show the statistic as a per- 
centage of the node’s total network receives. 

Packet error, transmit: 

Counts the number of times an error occurs during transmission of a 
message. The system increments counts for this statistic when other 
error conditions occur. The display formats show the statistic as a per- 
centage of the node’s total network transmits. 

Timeout, receive: Counts messages received that did not complete in the expected time. 

The display formats show the statistic as a percentage of the node’s 
total network receives. 

Timeout, transmit: Counts transmitted messages that do not complete their transmission in 

the expected time. This error often occurs when network traffic is 
slow, due to repeated attempts to retransmit or regenerate the ring 
token. The display formats show the statistic as a percentage of the 
node’s total network transmits. 



Using Netmain A-23 




Transmit call: 



Counts the number of requests to transfer data out of the node, on to 
the ring. The transmit call counter is increased even if the actual 
transmit fails. This performance statistic does not reflect any error 
conditions. If the number of requests is less than 100 percent of the 
ring transfers attempted, the node had to retry some of the transfers. 
The display formats show the statistic as a percentage of the node’s 
total network transmits. 

Transmit error, receive: 

Counts the number of times that either the transmitter or another re- 
ceiver had an error in the packet. For this error to occur, some other 
error flag must be set. The display formats show the statistic as a per- 
centage of the node’s total network receives. 

Receives as percentage of network I/O: 

Calculates the ratio of incoming messages (receives) to the node’s total 
network I/O. The performance statistic is shown as a percentage of the 
node’s total network traffic. If the count for this statistic is 43 per- 
cent, for example, incoming messages account for 43 percent of all the 
node’s network I/O activities. 

Sends as percentage of network I/O: 

Calculates the ratio of transmitted messages (sends) to the node’s total 
network I/O. The performance statistic is shown as a percentage of the 
node’s total network traffic. If the count for this statistic is 43 per- 
cent, for example, outgoing messages account for 43 percent of all the 
node’s network I/O activities. 

Total network activity: 

Measures the total network activity (sends plus receives) of each node. 
You should use this performance statistic only with plots of network 
totals or rates. Total network activity per node is shown as a percent- 
age of the total network activity for the entire network. 



ESTJTOPOLOGY - Topology Information 

The ESTJTOPOLOGY probe writes information collected by the TOPOLOGY probe (see 
below) to the netmain_srvr log file. 

Default Probe Interval Time: 1:00:00 

Default Probe Skip Distance: 1 



HW_FAIL - Hardware Failure Messages 

The HW_FAIL probe records every change in the hardware failure message reported by 
the nodestat command, on the node that is running the monitor. The “ring hardware fail- 
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ure” message identifies the node that last reported a ring hardware failure. Use the mes- 
sage to locate the problem node or cable in the network. The node that reports the failure 
is often contiguous to the failure or is experiencing the failure. 

Default Probe Interval Time: 0:01:00 

Default Probe Skip Distance: Not Applicable 

Hardware failure messages are generated by Domain/OS. They appear when there is no 
network traffic, and Domain/OS is completely unable to send network messages. 



MEMORY - Records Counts of Memory Errors on Nodes in the Network 
The MEMORY probe lists nodes on which correctable memory errors have occurred. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 



NET_SERVICE - Network Service Queue Statistics 

The NET_SERVICE probe measures the length of the network service queue backlog on 
each node. The length is the number of network service requests that remain in the queue 
immediately after a request is serviced. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 

File server, any backlog: 

Shows the number of times that each node’s file server noted one or 
more file service requests in the file server queue. Any requests left 
in the queue create a queue backlog. The file server checks for a 
backlog every time it services a request. The file server handles only 
requests from other nodes for operations such as opening, closing, and 
creating files (not reading or writing) . Output formats show the num- 
ber of times a backlog was present as a percentage of the number of 
file services requested by other nodes. 
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File server, average backlog: 

Shows the average number of file service requests in each node’s file 
server queue. Every time it services a request, the file server checks 
for remaining requests (the queue backlog) and counts these remaining 
requests. When there are no requests, the performance statistic adds 
a 0 to the average. The file server handles only requests from other 
nodes for operations such as opening, closing, and creating files (not 
reading or writing). Backlog incidence is shown as a percentage of the 
queue’s capacity. 

File server, backlog severity: 

Shows the average length of each node’s file service backlog. Every 
time it services a request, the file server checks for remaining requests 
(the queue backlog). If a backlog exists, the number of requests the 
queue contains are used for averaging in this performance statistic. 

The file server handles only requests from other nodes, for operations 
such as opening, closing, and creating files (not reading or writing). 
Incidence is shown as a percentage of the queue’s backlog capacity. 

File service queue overflow: 

Shows the number of rejected requests for file services for other 
nodes. A node rejects file service requests when it already has too 
many other requests pending. Rejections slow down the node that 
made the request and can cause errors. When a node has service 
queue overflows, it can indicate that too many other nodes require 
data stored on this node. Output formats shows this statistic as a per- 
centage of the file service requests made to each node. 

Total file service: Shows how many file services each node performs for other nodes 

(not file services the node performs for its own benefit). You should 
use this performance statistic only with plots of network totals or rates. 
File services are activities such as opening and creating files, and di- 
rectory lookups. (The paging server handles file reads and writes.) 

Paging server, any backlog: 

Shows the number of times that each node’s paging server noted one 
or more page service requests in the page server queue. Any requests 
left in the queue create a queue backlog. The paging server checks for 
a backlog every time it services a request. The paging server handles 
only requests from other nodes, for reads, writes, paging, and several 
internal operating system services. Incidence plots show the number of 
times a backlog was present as a percentage of the number of page 
services requested by other nodes. 
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Paging server, average backlog: 

Shows the average number of page service requests in each node’s 
page server queue. Every time it services a request, the paging server 
checks for remaining requests (the queue backlog) and counts these 
remaining requests. When there are no requests, the performance 
statistic adds a 0 to the average. The paging server handles only re- 
quests from other nodes for reads. Backlog incidence is shown as a 
percentage of the queue’s capacity. 

Paging server, backlog severity: 

Shows the average length of each node’s paging queue backlog. Every 
time it services a request, the paging server checks for remaining re- 
quests (the queue backlog). If a backlog exists, the number of re- 
quests the queue contains are used for averaging in this performance 
statistic. The paging server handles only requests from other nodes, for 
reads, writes, paging, and several internal operating system services. 
Incidence is shown as a percentage of the queue’s backlog capacity. 

Total paging service: 

Shows how many paging services each node performs for other nodes 
(not file services the node performs for its own benefit). You can use 
this performance statistic only with plots of network totals or rates. 
Paging services are activities such as reads, writes, normal paging, and 
some internal operating system services. (The file server handles file 
opening, file creations, and directory lookups). 

Reads requested: Shows the number of pages that each node has read from other nodes 

in the network. Nodes read pages during file I/O or any other paging 
activity. Output formats that use percentages show the statistic as a 
percentage of all the node’s reads and writes to other nodes. 

Reads serviced: Shows the number of pages on each node that have been read by 

other nodes in the network. Nodes read pages during file I/O or any 
other paging activity. Output formats that use percentages show the 
statistic as a percentage of all services the node performs for other 
nodes. 

Writes requested: Shows the number of pages each node has written to other nodes. 

Nodes write pages during file I/O, operating system execution, and 
many other activities. Output formats that use percentages show the 
statistic as a percentage of all the node’s reads and writes to other 
nodes. 

Writes serviced: Shows the number of pages written to each node, by other nodes. 

Nodes write pages during file I/O, operating system execution, and 
many other activities. Output formats that use percentages show the 
statistic as a percentage of all services the node performs for other 
nodes. 
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PAGING - Diskless/Partner Information 

The PAGING probe records information about diskless nodes and their paging partners. 
Default Probe Interval Time: 0:30:00 
Default Probe Skip Distance: 1 
Diskless nodes/paging partners: 

Produces a display of diskless nodes and their paging partners. This 
display cannot be used with data taken from a running monitor. Use it 
to analyze data from log files. 

Paging partners, ordered by diskless node: 

Shows the node(s) used as paging partner (s) by each diskless node. 

Paging partners, ordered by mother node: 

Shows the diskless node(s) supported by each node that that volun- 
teered as a paging partner. 



SWD_10_MSGS - Software Diagnostic Messages (10) 

The SWD_10_MSGS records counts for various performance statistics on a node, both be- 
fore and after a 10-message broadcast. The data collected reflect the effect of receipt of 
messages on the node’s performance statistics. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 

SWD ack parity: Counts the number of parity failures in the hardware protocol seg- 

ments of software diagnostic messages. The hardware always detects 
ACK parity errors if any occur. The SWD_10_MSG and 
SWD__100_JV1SG probes collect data for this performance statistic. 

The display formats show the statistic as a percentage of the test mes- 
sages the node receives. 

SWD bus error: Counts errors during Direct Memory Access (DMA) from the ring 

controller, during receipt of software diagnostic messages. The 
SWD_10_MSG and SWD_100_MSG probes collect data for this per- 
formance statistic. The display formats show the statistic as a percent- 
age of the test messages received by the node. 
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SWD CRC: 



Counts test messages that contain Cyclical Redundancy Check (CRC), 
errors, detected by the ring hardware. CRC errors can result from er- 
rors in any part of the received message except the hardware protocol 
segments. Note that this performance statistic shows only those errors 
that occur in software diagnostic messages. The SWD_10_MSG and 
SWD_100__MSG probes collects data for this performance statistic. 

The display formats show the statistic as a percentage of the diagnostic 
messages received. 



SWD end-of-range: 

Counts the number of times that one or both of the message fields in 
the test message received was larger than the Direct Memory Access 
(DMA) channel allowed for it. The SWD_10_MSG and 
SWD_100_MSG probes collect data for this performance statistic. The 
display formats show the statistic as a percentage of the test messages 
the node receives. 

SWD header checksum: 

Counts SWD (Software Diagnostic) messages that contain checksum 
errors in the message header. Since the operating system program that 
verifies header checksums is usually disabled, the count for this statis- 
tic should be 0. The SWD_10_MSG and SWD_100_MSG probes col- 
lect data for this performance statistic. The display formats show the 
statistic as a percentage of the test messages the node receives. 

SWD messages not received: 

Shows the percentage of Software Diagnostic messages sent to a node 
but not received, as a percentage of the total number of SWD mes- 
sages sent to the node. The SWD_10_MSG and SWD_100_MSG 
probes collect the data for this performance statistic. 



SWD modem err: 

Counts the number of times the receiver could not synchronize prop- 
erly with the network, during receipt of SWD messages. The condi- 
tions that cause this error class are biphase or Elastic Store Buffer 
(ESB) errors. The SWD_10_MSG and SWD_100_MSG probes collect 
data for this performance statistic. The display formats show the statis- 
tic as a percentage of the SWD test messages the node receives. 

SWD overrun: Counts the number of Direct Memory Access (DMA) overruns that 

occur during software diagnostic messages. The SWD__10_MSG and 
SWD_100_MSG probes collect data for this performance statistic. The 
display formats show the statistic as a percentage of the test messages 
the node receives. 
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SWD packet error: Counts the number of times either the receiver or the transmitter had 
problems in SWD (Software Diagnostic) messages. If the fault was in 
the receiver, other counts are incremented also. The SWD__10_MSG 
and SWD_100_MSG probes collect data for this performance statistic. 
The display formats show the statistic as a percentage of the test mes- 
sages the node receives. 

SWD receive timeout: 

Counts Software Diagnostic (SWD) messages received that did not 
complete in the expected time. The SWD_10_MSG and 
SWD_100__MSG probes collect data for this performance statistic. The 
display formats show the statistic as a percentage of the test messages 
received. 

SWD transmit errors: 

Counts the number of times that either the transmitter or another re- 
ceiver had an error in a Software Diagnostic test message. For this 
error to occur, some other error flag must be set. The SWD_10_MSG 
and SWD_100_MSGS probes collect data for this performance statis- 
tic. The display formats show the statistic as a percentage of the test 
messages received by the node. 



SWD_100_MSGS - Software Diagnostic Messages (100) 

The SWD_100_MSGS records the effect of 100-message broadcasts, in the same manner 
as SWD__10JMSGS above. This probe collects the same information as SWD_10_MSGS. 

Default Probe Interval Time: 0:30:00 

Default Probe Skip Distance: 1 



TIME_SKEW - Difference Between Node Clocks 

The TIME_SKEW probe detects differences between the node clocks. 

Default Probe Interval Time: 3:00:00 

Default Probe Skip Distance: 1 

Compute offset times: 

Automatically computes offset times for each log file. The computed 
offset times are derived from the contents of the log files, using results 
from the TIME_SKEW probe. A variety of conditions can prevent the 
offset computation from working. For instance the TIME_SKEW 
probe may never have executed or may not have operated on each 
node. 
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TOPOLOGY - Total Node List Estimate 

The TOPOLOGY probe provides total node count (estimate). 

Default Probe Interval Time: 1:00:00 

Default Probe Skip Distance: Not Applicable 

Topology list from node total: 

A monitor keeps an estimate of the complete ring topology. The esti- 
mate represents a running total of lcnode results, not just the most 
recent result. This topology list will probably be longer than the list 
produced by the lcnode command, especially if the monitor has been 
running for a long time. In particular, it may list nodes that are not 
currently running. See also “ESTJTOPOLOGY” above. 



MODEM_ERRS - Transmit Modem Errors 

This observer reports on nodes that have more than five times the average number of 
“Transmit Modem Errors. “ 

Default Probe Interval Time: 0:30:00 

Default Recheck Interval: 12:00:00 



WIN_CRC - Disk Drive Errors 

This observer reports on nodes that have more than 0.01 percent of Winchester disk drive 
CRC errors. 

Default Probe Interval Time: 0:30:00 
Default Recheck Interval: 12:00:00 

A.4.3 Using netmain_srvr to Build Topology Lists 

The netmain_srvr and the netmain interactive tool provide several kinds of topology lists 
for the Apollo Token Ring network, including a Master Topology List. The Master To- 
pology List includes: 

® The direction of data flow in the network: the monitor from which information is 
collected and all nodes downstream of that node 

© All nodes whether or not they are currently connected to the network 
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• Each node's hexadecimal ID 



• Diskless nodes 

Additional information that should be added to this list includes 

• Loop number 

• Node type 

• Paging partners of diskless nodes 

• Network servers running on the node 

• Node administrator’s name (if they occur at your site) 

• Node location 

When complete, this list is the network’s Master Topology List. The Master Topology List 
provides the foundation for allocating network resources and for monitoring and “tuning” 
network performance. 



The netmain_srvr Topology Lists 

When you run netmain_srvr, the server process creates a Total Node List. The list is 
netmainjsrvr’s best estimate of what the network topology would look like if every node 
in the network were switched on. To generate the list, netmain_srvr*s TOPOLOGY probe 
performs the equivalent of the lcnode command at scheduled intervals. 

Under normal operating conditions, if the TOPOLOGY probe runs for several days to a 
week, it produces a complete network topology list. Since it is repeated at scheduled inter- 
vals, the TOPOLOGY probe may find a node at some probe that it did not not find in 
previous probes. The node may have been newly installed, its loop may have been 
switched out during a previous probe, or it may have been powered down or not communi- 
cating on the network. The TOPOLOGY probe adds newly acquired node information to 
netmain_srvr’s Total Node List. 

The EST_TOPOLOGY probe writes netmain_srvr’s Total Node List to the *node_data/ 
system_logs/net_log directory. The directory contains logs from all netmain_srvr probes 
and observers. The netmainjsrvr uses non-ASCII files for its work. You can look at the 
files in ‘node__data/system_logs/net_log by using the netmain interactive tool. In fact, this 
tool provides the only means you have of looking at any information in netmain_srvr’s 
net_log files. (You can look directly at error logs.) 
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To generate the Master Topology List, run netmain_srvr with its default options. If you 
use the netmain interactive tool on the monitor while you are collecting a topology list, be 
sure the TOPOLOGY and EST_TOPOLOGY probes remain active. After you have run 
netmain_srvr for several days to a week, enter the netmain interactive environment from 
the shell. Choose the Find Monitors and Nodes menu. Use “F4 Topo list from node to- 
tal” to cause netmain_srvr’s Total Node List to be written to the netmain environment. 
When the topology list status message tells you the list is written, you can use “F6 Display 
topology list” to display the topology list. Verify that the total of nodes on the list equals 
the total of nodes in your network. If it does not, let the monitor run longer. Store the 
topology list on line and post printed output in the network control room. Section A. 5 de- 
scribes how to save displays generated with the netmain tool. Add the additional informa- 
tion, listed above, to the topology list after storing the list as an ASCII text file. 

The netmain tool can also generate a topology list by executing the lcnode command 
once. From the Find Monitors and Nodes menu, use the “F3 Topo list” from lcnode 
command to generate the list. Use the F6 command to display the list. This topology list 
has the same uses, advantages, and drawbacks as those described for the lcnode com- 
mand. 

In large networks, subsets of the Master Topology List are often useful. A subset of the 
master list might contain, for example, only DN3000 nodes. Different types of nodes per- 
form differently. Special purpose topology lists can readily show the kinds of nodes that are 
experiencing problems or unexpected patterns of use. Use special-purpose topology lists 
and performance statistics to improve network performance. 

If your network extends through several buildings, use subsets of the Master Topology List 
to identify all nodes in a single building. Use the list to identify conditions applicable only 
to that building, for example, to isolate problems caused by interference in power supply. 

Finally, you should have a topology list of all nodes running monitors in the network. The 
F2 command “Find all monitors” will generate this list. 



A.4.4 Using netmain_srvr to Gather Performance Statistics 

The topography and topology lists provide base-level information about your network. Set 
up a system of regularly scheduled reports from netmain_srvr monitors to build a picture 
of the network’s performance over time. 

The netmain_srvr is the main source of network performance statistics. Shell commands 
can provide limited information on the performance of nodes and the network. Use net- 
main_srvr as part of an ongoing network maintenance effort because it is the only means 
of collecting information about 

• Events as they occur over time 

• The time at which an event count begins 



Using Netmain A-33 




• An event's pattern of occurrence 

• Events that occur regularly, but at a low frequency (for example, 1 in 10,000 
times) 

In addition to generating topology lists, netmain_srvr collects more than 75 different statis- 
tics (defined earlier in this section) on node and network performance and error condi- 
tions. You control netmain__srvr probes and observers with netmain_srvr configuration 
files or the netmain interactive tool. Both allow you to specify 

• What data is collected 

• How often the data is collected 

The netmain interactive tool also allows you to 

• Change specifications on active monitors 

• Choose a variety of output formats for the data 

(See Section A. 5 for more information on the netmain tool.) 



Relationship of netmain_srvr Probes to Network Topology 

Information on the ring originates at a transmitting node or source. The source node sends 
data by placing a message, or packet, on the ring. The packet contains the destination ad- 
dress of the node that the packet is for. 

When it receives a packet, a node examines the packet’s destination address. If the desti- 
nation address matches the node’s ID, the node 

• Copies the packet into its memory 

• Modifies the packet to acknowledge successful (or unsuccessful) receipt 

• Sends the modified packet to the next node 

When a node receives a packet with a destination address that does not match its own ID, 
it sends the packet to the next downstream node. When a packet returns to its source 
node, the source node removes the packet from the ring and examines the packet to de- 
termine if it was successfully received. 
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The netmain_srvr probes report on the state of 

© The hardware that sends and receives packets, specifically the ring controller and 
modem 

© The packet transmission protocols, the condition of the packets sent and received, 
the number of packets delayed or lost, and the total number of packets sent and 
received 

A node may be unable to send or receive messages if its ring hardware is not functioning 
properly. If some part of the route between the source and destination nodes is com- 
pletely broken, the message will never arrive at the destination node. 

A packet can leave a node only if it has the correct format. However, a message can ar- 
rive at the destination node in a corrupted state for several reasons. Frequently the cause 
is a weak signal or intermittent signal interference on the coaxial cable. All nodes cause 
momentary instability on the ring when they are put into the network. That momentary 
instability can cause a packet to become corrupted. 

Both serious and minor conditions are reflected in network data. A ring hardware failure is 
serious and requires immediate attention. Other conditions can slow down overall network 
performance but do not cause complete network failure. 

All nodes monitor the condition of packets whether or not the packet is intended for the 
node. Error conditions indicating hard breaks in the network are detected by using the 
broken-link detection mechanism. Nodes that are downstream of a break report the fail- 
ure; source nodes upstream of a break are unable to send messages past the broken link. 

In addition to the data described above, other netmain_srvr probes report on both normal 
and potentially problematic performance of storage volumes. 



Probes Reporting Error Conditions 

The probes named in Table A-l detect potentially serious node and network error condi- 
tions. Any of these errors can happen at random, in short bursts. In these cases, the cause 
is usually a momentarily weak signal. However, if the counts of these probes show a 
steady increase, there is reason to suspect a problem with a disk, a node, or network ca- 
ble. 
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Table A-l . netmainjsrvr Probes Reporting Serious Error Conditions 



Probe 


Level of Error 


DISK_ERRS 




CRC errors 
Seek errors 
Equipment check 


Count should not be higher than 0.01% 
Count should not be higher than 0.01% 
Count should not be higher than 0.01% 


ERR_COUNTS 




Receive Header Checksum 
Biphase Error 
ESB Error 
Modem Error 
Transmit No Return 


Count should be 0 
Can indicate hard break in network 
Can indicate hard break in network 
Can indicate hard break in network 
Can indicate hard break in network 


HW_FAIL 


Indicates hard break in network 



Probes Reporting on Network Performance 

The netmainjsrvr probes track the services nodes perform for each other. These are 



© Paging service— transferring 1024-byte pages of objects from one node to another 

• File service— requests from remote nodes to create, open, or close a file on the 
local node 

• Reading pages on and writing pages to other nodes 
® Serving as a paging partner for diskless nodes 

Node CPU and disk activity is closely related to the services nodes perform for each other; 
netmainjsrvr also collects information on this activity. Table A-2 shows the 
netmainjsrvr node and network performance statistics that can be useful for allocating 
network resources. 
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Table A-2. netmainjsrvr Probes Reporting on Network Performance 



Probe 


Event to Monitor 


CPU_TIME 


Aegis CPU 
User CPU 


DISK_ERRS 


Total Storage Module Activity 
Total Winchester Disk Activity 


NET_SERVICE 


File Server Backlog 
Paging Server Backlog 
Reads/Writes Requested 
File Server Queue 
All Paging Server Queue 
Reads/Writes Serviced 
Total File Service 
Total Paging Service 


PAGING 


Monitor all events generated by this probe 



Controlling netmain_srvr’s Data Collection Characteristics 

The netmainjsrvr can collect a large amount of data, but you can limit the number of 
active probes on each monitor if there is a shortage of disk space in the network or if you 
simply find it easier to do so. For example, you might configure a monitor to collect only 
topology data, another to collect network performance statistics, and another to collect er- 
ror statistics. 

Decrease a probe’s sampling interval time and skip distance; that is, cause the probes to 
collect information more often, especially when you suspect a problem with a node, a loop, 
or the network. Decrease the default schedules if you need greater detail about some net- 
work performance events or if your service representative requests the information for net- 
work maintenance purposes. The default probe sampling intervals are sufficient for most 
network data collection purposes. 

Use the netmain interactive tool’s Alter Probe Timing submenu to change sampling inter- 
vals and skip distance on an active monitor. In netmainjsrvr configuration files, 

-observer and -sample options control the sampling interval time. The -skip option con- 
trols the skip distance. 

You can explicitly set a limit on the length of the log files written by netmain_srvr. Use 
the -11 (log length) option in netmain_srvr configuration files. The netmain interactive 
tool’s Alter Logging Controls submenu allows you to limit log file size. For regular network 
data collection, it is good practice to 

© Limit the length of log files; the default length is usually adequate, but verify this 
by regularly inspecting log size when you first start monitors or change monitor 
parameters. 
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• Automatically start new log files after you close old log files; this is the default and 
should not be overridden by the configuration file option -nl. 

® Use the Alarm Server -disk [n] option on user nodes running monitors. A user 
logged on to that node will receive notice of a potential disk overflow condition. 
The Alarm Server startup is explained in Chapter 3 of this book. 

Limiting the number of probes on each monitor, closing the log files, and opening new 
ones frequently (for example once a week) is usually sufficient to ensure that 
netmainjsrvr does not overwrite data because disk space is used up or log length is 
reached. After starting netmain_srvr processes on nodes, check the log files written by the 
servers on a regular basis, typically once a week. Copy old netmain_srvr log files to floppy 
disk or tape for later analysis and permanent storage. 



A. 5 The netmain Interactive Tool Reference 

This section describes netmain, the interactive tool used to manage the network and to 
diagnose problems with individual nodes or disks. It provides complete reference informa- 
tion on the tool and describes how to invoke and use it. 

The netmain interactive tool can manage netmainjsrvr monitors. The netmain_srvr 
monitors collect information used to allocate network resources and diagnose network 
problems. Most of this sections contains reference information on all netmain menus. 

The contexts in which to use netmain are described in Section A.l of this Appendix. 

Refer to this description of netmain when you set up a network management program and 
when you work with the tool. If you have never used netmain, practice with the tutorial at 
the beginning of this Appendix (Procedure A-2) . The tutorial does not give detailed infor- 
mation about the menu commands. Its purpose is to allow you to become familiar with 
controlling the the netmain menus. Read the descriptive information in this Section on 
netmain before or after you practice with the tutorial. 

You can configure netmain_srvr from the command line (see Section A. 4), or you can 
start a server process and use the netmain interactive tool to configure it. The menu and 
submenu descriptions below reference the server options controlled from each menu. 

When netmain_srvr is running, the netmain lets you control netmain_srvr monitors, 
change parameters, and analyze the information in the log files. In addition, netmain pro- 
vides output formats and graphic displays of the information collected by the netmain^sTyr 
process. The tool provides online help about menu usage and about every menu item. 
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A. 5.1 Invoking netmain 



Use the shell command ps (UNIX operating system command) or pst (Aegis command) to 
verify that a monitor is running before you start using netmain. The tool can find moni- 
tors that have been running for approximately 30 seconds. If the tool cannot locate it, the 
monitor may be experiencing a problem. 

Invoke netmain from the shell command line as follows: 



$ netmain 

You can run the netmain interactive tool in an icon window by selecting the F6 box in the 
Top Level menu and using the space bar to create the icon. Open the window from its 
icon mode by placing the cursor in the icon and pressing the space bar once. 

When you use netmain, select a netmain_srvr monitor to work with before using any 
other feature of the program. 



A. 5. 2 The netmain Top-Level Mepn 

When you invoke netmain, the program displays its Top-Level menu, shown in 
Figure A-5. The commands on the menu are described in Table A-3. Use the Top- 
Level menu to 

o Invoke the other menus 
o Run netmain in an icon window 
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Figure A-5. Top-Level Netmain Menu 
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Table A-3. Top-Level Commands 



Command Box 



Description 



FI - Find monitors and nodes 



Invokes a submenu that selects a single monitor from 
which to collect information or generate reports about 
monitors or nodes. Use this submenu to select moni- 
tors or to create and manipulate network topology lists. 



F2 - Change monitor behavior 



Invokes a submenu that redefines the netmain_srvr 
parameters. Use this submenu to change the behavior 
of an active monitor or to close an active log file for 
examination. 



F3 - Analyze network data 



Invokes a submenu that formats data and displays it 
on the screen. You can copy formatted data to a file 
for printing at a later time. Use this submenu to for- 
mat data from an executing monitor or from a log file 
that has been closed. 



F 6 - Shrink window to icon 



Runs the program in an icon window. 



F7 - Help me use menu 



Provides online help. 



F8 - Exit 



Quits the program. 



A.5.3 The netmain Find Monitors and Nodes Menu 

Figure A-6 shows the Find Monitors and Nodes menu. Use the Find Monitors and Nodes 
menu to 



• Find monitors 

• Select monitors for use 

• View network topology lists 
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Figure A-6. Find Monitors and Nodes Menu 

The FI and F2 command boxes in this menu find specific monitors. The F3 through F6 
command boxes write to and display the topology list. Table A-4 explains each command 
box in the Find Monitors and Nodes menu. 

Table A-4. Find Monitors and Nodes Commands 



Task 


Command Box Used 


Explanation 


Select a monitor for 
examination or 
configuration 


FI— Choose a specific 
monitor 


Selects a monitor for work or 
analysis. Use this option when 
netmain reports “No Monitors 
are Known,” to examine the log 
file currently open for this monitor; 
or the monitor itself; or to recon- 
figure the monitor. Use the input to 
specify the monitor by following the 
guidelines in the help box. 


; 

! 


i 


Netmain finds the monitor and 
draws a box containing that node's 
name. If it can't find the monitor, 
netmain reports “Node appears not 
to have a monitor.” This can 
happen if 






• The monitor is busy and cannot 
respond 

• The monitor has stopped running 

• The network is broken so that 
messages are not transmitted 
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Table A-4. Find Monitors and Nodes Commands (Cont.) 



Task Command Box Used 



List all monitors F2— Find all monitors 



Fill topology list F3— Topo list from 

with current lcnode lcnode 

information 

Fill topology list F4— Topo list from 

with an estimated node total 

of all the nodes 

physically connected 

to the network 

— even those not 

communicating on 

the network 



Explanation 

If the monitor is busy, try the com- 
mand a second time if you receive 
this message. 

You cannot use other netmain 
features until you choose a monitor. 

Finds all monitors, using the current 
topology list (see F6). If the 
topology list is empty, netmain 
executes lcnode and writes the 
results to the Topo list. Status 
messages appear as the program 
searches for monitors. Netmain 
draws a box containing the name of 
each monitor it finds. Select a 
monitor by pointing to the box. 
Netmain encloses it with stripes. 

Executes lcnode and writes the 
information to the Topo list. 

To display the list, use the F6 
command box. 

Takes the Total Node list 
stored in the monitor selected 
and writes it to the Topo list. 

Since the Total Node list is a 
cumulative list of nodes that the 
monitor found after several 
lcnodes, it should be the most 
complete online list of all the 
nodes in the network. When 
the monitor has run for a week, 
the Total Node list should include 
all nodes that have been on the 
network since the monitor started. 
The list may be longer than the 
current lcnode report. If you are 
using the monitor on the local 
node, netmain gets a Total Node 
list without generating network 
traffic. Use this command on a 
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Table A-4. Find Monitors and Nodes Commands (Cont.) 



Task 



Command Box Used 



Explanation 



Fill topology 
list from a file 



F 5— Topo list from 
data file of nodes 



local monitor when you need to 
generate a topology list during 
network problems. To display the 
topology list, use the F6 command. 

Prompts for a filename and list 
writes its contents to a topology 
list. Use a log file or create a text 
file. If you create a text file, list 
node names or hexadecimal IDs, 
separated by spaces, or listed on 
different lines. Comment lines 
must start with the characters # or 
{, and the text must run to the end 
of the line. Use this command to 
build a Master Topo list or special 
purpose lists, for example, a list of 
nodes that run netmain_srvr or 
any of the network servers. 

The help box shows how netmain 
resolves relative pathnames. 

To display the contents of the 
topology list, use the F6 command 
box. 

If you don’t enter a filename in 
response to the prompt, netmain 
displays an error message. 



View current 


F6 — Display Topo list 


Displays the current contents of the 


network or 




topology list in a read-only pad. 


topology kept in 




You can use other commands 


stored topology 




(F3, F4, F5) to fill the topology 


list. 




list with particular information. If 
you have not used one of these 
other commands yet, netmain 
performs an lcnode, fills the 
topology list with the results, and 
displays the contents of the list. To 
save the list, use the DM pn 
command. 
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A.5.4 The netmain Change Monitor Behavior Menu 

The Change Monitor Behavior menu allows you to manipulate monitor behavior. The 
netmainjsrvr option -topo [init] corresponds to the F6 command in this menu. In order 
to use this menu, you must select a monitor by using the Find Monitors and Nodes menu. 
Then you can use this menu to 

• Close a current log file so you can analyze its contents 

• Schedule probes to run more frequently 

• Reschedule observers 

• Configure data collection parameters for each monitor 

Figure A-7 shows the Change Monitor Behavior menu, and Table A- 5 lists each command 
box in the menu. 
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The following nodes have monitors: 




Figure A-7, Change Monitor Behavior Menu 
Table A-5. Change Monitor Behavior Commands 



Task 


Command Box Used 


Explanation 


Set parameters 


FI— Alter logging 


Invokes as submenu that starts 


for log file 


controls 


new log files, which allow you 
to change logging parameters. 


Set parameters 


F2— Alter probe timing 


Invokes a submenu that reschedules 


for probes, 




probe active and waiting periods 


list probes 




and probe skip distances. 
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Table A-5. Change Monitor Behavior Commands (Cont.) 



Task 


Command Box Used 


Explanation 


Set parameters for 
observer and list 
observer 


F3— Alter observer 
timing 


Invokes a submenu that reschedules 
the intervals at which observers 
wake up to check for conditions. 


Send a text message 
to a monitor 


F4— Log a text string 


Prompts for a line of text that 
can contain up to 80 characters 
and sends the text to the selected 
monitor. To select a monitor, point 
to the box that contains its name. 
Netmain encloses the box with 
stripes. If the monitor name box is 
not displayed, return to Find 
Monitors and Nodes menu and 
choose “F2— Find all monitors”. 


Stop a monitor 


F5— Kill monitor 


To stop a monitor from netmain, 
point to the box that contains its 
name. Netmain encloses the box 
with stripes. If the monitor name 
box is not displayed, return to a 
Find Monitors and Nodes menu, 
choose “F2— Find all monitors”. 






Note that once you stop the 
monitor, you must restart it. 


Update a monitor’s 
node list when the 
TOPOLOGY probe 
cannot 


F6— Add topo file to node 
total 


Updates the chosen monitor’s 
Total Node from a topology list 
in a text or log file. Use this feature 
only if the network failed and the 
TOPOLOGY probe on a monitor 
you just started cannot get topology 
information to update the list. This 
feature should not be used at other 
times because, if the topology list 
used does not include all nodes, the 
monitor will not collect data from 
any nodes not in the topology list. 






The help box shows how netmain 
resolves relative pathnames. 
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Using the Change Monitor Behavior Menu 

When you are using the Change Monitor Behavior menu, do not use CTRL/Q (Quit a 
process) between the time you select the “Perform changes” commands and the time the 
message “Node_name acknowledged” appears. Doing so may cause unpredictable monitor 
behavior. 

A. 5. 5 The netmain Alter Logging Controls Submenu 

The Alter Logging Controls submenu displays the parameters in effect for the log file cur- 
rently in use. There are two versions of this menu, the one displayed depends on the 
monitors logging behavior. The parameters are the same as the following netmain_srvr 
options. 

Option Meaning 

-l|-nl Write or do not write to a log file 

-1 [pathname] The log file name 
-11 n Limit the size of the log file 

Use the Alter Logging Controls submenu to 

• Change the parameters in effect for a log file, or 

• Cancel changes and return to the parameters most recently in effect 

The Alter Logging Controls submenu is shown in Figure A-8. Table A-6 lists each com- 
mand box in the submenu. 
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Figure A-8. Alter Logging Controls Submenu 



Table A-6. The netmain Alter Logging Controls Submenu 



Task 


Command Box Used 


Explanation 


Change parameters 
of log files 


FI— Perform logging 
changes 


Causes the changes you make to 
take effect. 


Cancel changes to 


F2— Revert to original 


Abort the changes. When you use 
the Alter Logging Controls sub- 
menu, you make changes on a 
“scratch pad.” Select FI to make 
the changes. Select F2 to abort the 
changes. 






Changes take effect when the status 
message, “Node_name acknowl- 
edged” appears. 
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Table A-6. The netmain Alter Logging Controls Submenu (Cont.) 



Task 


Command Box Used 


Explanation 


Get assistance with 


F7— Help me use 


Gives online help for using the 


the menu 


the menu 


menu. 


Exit this menu 


F 8— Return to 


Returns to the Change Monitor 




“Change” menu 


Behavior menu. 



Using the Alter Logging Controls Submenu 

The number of option boxes that you see in the Alter Logging Controls submenu depends 
on the monitor’s current logging behavior. If you start netmain_srvr with the default op- 
tion, log files are always written (unless you stop them), and the submenu displays three 
option boxes that describe the log file parameters. If the -nl option was used at monitor 
startup, no logging is performed (unless you start logging), and the submenu displays just 
one option box. Figure A-8 shows the top sections of both menus. 

In both versions, the long rectangular left-hand boxes report the status of each parameter. 
The long rectangular right-hand boxes name or describe the parameter. To change a pa- 
rameter, you can select either the left-hand or the right-hand box. To start logging, select 
either box in Menu A. Menu B then appears. 

Use the first box in Menu B, “Logfile is already being written”, to close a log file. The 
options at monitor startup determine whether a new log is written. If the -nl option was 
used, no new log file will be written. If the option was not used, a new log file starts once 
you close the original file. Before closing a file you plan to analyze, note its name; you 
must enter the name in the Analyze Network Data menu. Use the second box in Menu B, 
“Original log file name”, to change the name of a log file. Netmain automatically closes 
the current file and opens a new log file with the filename you provide or with the default 
name net_log.yy.mm.dd. (Either name is relative to the ‘node_data/system_logs/net_log 
directory.) If netmain creates more than one default log file on the same date, it appends 
a suffix, using alphabetical order, to the log file names. Three log files created on the same 
day would be named 

net_log.83.08.19 netjog.83.08.19_a netjog.83.08.19_b 

When you change the name, the new name appears in the left-hand box, and the message 
“Logging will be shut down and restarted” appears. If you choose to use the default name, 
the next message says “Using default name.” 

Use the bottom box in Menu B, “Limit on log file length”, to display the length to which 
the current log file can grow or to limit the length of the new log file (the one displayed in 
the middle box). The length is in units of 1 kilobyte (1024 bytes); the default length is 
3000 (3 megabytes). You cannot change the limit for a current log file. 
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Note that if a log file reaches the maximum length and netmain needs to write more data, 
the program starts to write over the oldest data in the log file. If you want to save this old- 
est data, you should close the file and store it when it approaches its maximum length. 

If you attempt to leave the submenu without choosing “Fl-Perform logging changes” or 
“F2-Revert to original logging,” an input box prompts “Do you want to perform the 
changes? [Y | N].” You must choose to perform the change or cancel the change in or- 
der to leave the menu. 



The netmain Alter Probe Timing Submenu 

The Alter Probe Timing submenu shown in (Figure A-9) displays the schedule used by 
each probe when it collects data. These parameters are the same ones as the following 
netmain_srvr options: 

-sample Probe time 

-skip Probe distance 

Use the Alter Probe Timing submenu to 

® Display the intervals at which probes collect data. 

® Change the scheduling intervals. Probes and their default data collection intervals 
are listed in Section A. 4. 

Table A-7 lists each command box in the Alter Probe Timing submenu. 
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Figure A-9. Alter Probe Timing Submenu 
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Table A— 7, The netmain Alter Probe Timing Submenu 



Task 


Command Box Used 


Explanation 


Change parameters of 
log files 


FI— Perform scheduling 
changes 


Causes the changes you make to 
take effect. 


Cancel changes to 
parameters 


F2— Revert to original logging 


Causes changes made to return 
last scheduled intervals in effect. 
When you use the Alter Probe 
Timing submenu, you’re making 
changes to parameters on a 
“scratch pad.” Select FI to cause 
the changes to take effect. If you 
make changes, then decide not to 
put them in effect, use F2 before 
you use FI to undo the changes in 
the scratch pad. 






The changes you make with FI 
take effect when the status message 
“Node_name acknowledged” 
appears. If you make further 
changes to parameters and choose 
F2, the logging parameters revert to 
the parameter changes that were 
most recently in effect. 


Show probes above 
those currently 
displayed 


F4— -Scroll Up 


The menu displays only eight 
probes at a time. If you are in 
the lower portion of the menu, use 
F4 to display the top portion of the 
menu. 


Show probes below 
those currently 
displayed 


F5— Scroll Down 


The menu displays only eight 
probes at a time. If you are in 
the upper portion of the menu, 
use F5 to display the bottom 
portion of the menu. 


Get assistance with 
the menu 


F7— Help me use the menu 


Gives online help for using the 
menu. 


Exit this menu 


F8— Return to “Change” 
menu 


Returns to the Change Monitor 
Behavior menu. 
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Using the Alter Probe Timing Submenu 

As shown in Figure A-9, which shows the top [art of the submenu, each probe name ap- 
pears in the long rectangular box at the right; parameters for the probe are on the left. 
Table A- 8 lists the probe parameters appearing in the leftmost boxes of the Alter Probe 
Timing submenu. 



Table A-8. Probe Parameters 



Task 


Parameter Box Used 


Explanation 


Probe scope 


First box on left 


Indicates whether the probe 
operates on all nodes or only 
on the node on which the monitor 
is running. You cannot change this 
parameter. 


Sampling interval 


Second box from left 


Indicates how often the probe 
operates in hh:mm:ss format. 

The actual probe sampling intervals 
are slightly longer than the number 
shown, especially on heavily used 
nodes. For information about 
probe defaults, see Section A. 4. 


Skip Distance 


Third box from left 

i 

».. , — . — , 


Indicates the distance between 
nodes checked in each pass around 
the ring. It is only relevant for 
probes that check every node. 

A default skip distance of 1 checks 
each node on each pass; a skip 
distance greater than the number of 
nodes in the ring checks a different 
node on each pass. For skip 
distances greater than 1, the probe 
starts with a different node on each 
pass. For example, a skip distance 
of 5 checks the following nodes on 
each pass: 
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Table A-8. Probe Parameters (Cont.) 



Task 


Command Box Used 


Explanation 






Nodes 1, 6, .. 
Nodes 2, 7, .. 
pass 

Nodes 3, 8, .. 


. on the first pass 
. on the second 

. on the third pass 






Nodes 1, 6, .. 


. on the sixth pass 


■ 

: 




Note that the numbers in the 
above example represent distances 
from the monitor around the ring. 
Node 1 runs the monitor, node 2 is 
the next node downstream, and so 
on. 



If you attempt to leave the submenu without choosing “Fl-Perform Scheduling Changes” 
or “F2-Revert to original scheduling,” an input box prompts “Do you want to perform the 
changes?” [Y | N]; you must choose to perform the change or cancel the change in order 
to leave the menu. 



Guidelines for Scheduling Probes 

When you first start to run monitors, you should schedule their probes to collect data very 
frequently so that you can compile a complete set of data. After several days or a week, 
you can reschedule the probes. 

When you start netmain_srvr on a node, leave the TOPOLOGY probe at its default time 
of 1 hour (01:00:00). Within 48 hours, the log files should include a fairly complete topol- 
ogy list; every node will most likely have been powered on and be online and communicat- 
ing on the network when the lcnodes were run. The netmain process then automatically 
reschedules the topology probe to run every 12 hours to conserve CPU time. 

If you change the network topology by adding, removing, or relocating nodes, change the 
sampling interval to every half hour or so. The netmain process will activate the TOPOL- 
OGY probe within 1/2 hour, and the lcnode performed by the topology probe will collect 
the information about new nodes. After this, the topology probe will again run only once 
every 12 hours. 

Note that when a node does not appear in an lcnode, the netmain_srvr leaves it on the 
total node list for some time, assuming that it is powered down, that the node’s loop is 
switched out, or that the node is not communicating on the network. If the node disap- 
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pears for more than a week, the netmain_srvr assumes that it is really gone and removes 
its name from the Total Node list. 

Probes that can check each node write a large amount of data to log files. When you con- 
figure these probes for each node running a monitor, determine how much disk space you 
want to allow the log files to consume each day. In general, log file storage requirements 

o Increase with the number of probes you use 
o Decrease as the sampling interval increases 
© Decrease as the skip distance increases 

When scheduling probes for your network, remember that log files reach their maximum 
size most quickly when you check many nodes, sample frequently, and run many different 
kinds of probes. Sampling less frequently does not fill up the log file quickly, but does not 
get as much detailed information. If you run fewer probes, you do not fill up the file as 
fast, but you get less complete information about the network. On any schedule, the 
longer the recording period, the fuller the log file gets. Make trade-offs based on your 
needs for network information. 

The check interval for each probe is the product of the probe’s sampling interval and the 
skip distance. The check interval determines how often the probe on a particular monitor 
actually checks each node. The following equation shows the check interval. 



c = rn s 
Where: 

c Is the check interval (i.e., how often the probe checks each node ) 
rn Is the probe n’s sampling interval 
s Is the skip distance 

Using this formula, we could schedule a monitor’s ERR_COUNTS probe, for example, to a 
skip distance of 10 and a sampling interval of 3 minutes (00:03:00). The check interval is 
30 minutes, so the ERR__COUNTS probe checks each node once every 30 minutes. 

If you are experiencing an ongoing problem with node or network performance or reliabil- 
ity, you should run probes at regular intervals, with more frequent samples and lower skip 
rates, in order to locate the problem. The smaller the check interval, the more data you 
will collect and the better your chances for detecting the problem. 

When you change probe scheduling parameters, each probe wakes up as soon as it is re- 
scheduled. If you reschedule a number of probes at the same time, avoid “bursts” of CPU 
activity by setting parameters for a single probe, (use “Fl-Perform scheduling changes” to 
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change the parameters) and then setting parameters for the next probe. If you change all 
parameters at once and then perform the scheduling changes, the probes all wake up at 
once. For a brief period, these multiple wake-ups can affect performance on the node 
running the monitor. 



The netmain Alter Observer Timing Submenu 

The Alter Observer Timing submenu (shown in Figure A- 10) displays the schedule used by 
each observer when it collects data. These parameters are the same ones as the following 
netmain_srvr options: 

-observe Observer time 

-reobserve Observer time 

Use the Alter Observer Timing submenu to 

• Display the intervals at which observers collect data 
® Change the scheduling intervals 

Observers and their default data collection intervals are listed in Section A. 4. 

Table A-9 lists each command box in the Alter Observer Timing submenu. 
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Figure A-10. Alter Observer Timing Submenu 
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Table A-9. The netmain Alter Observer Timing Submenu 



Task \ 


Command Box Used 


Explanation 


Change parameters 
of log files 


Fl—Perform scheduling 
changes 


Causes the changes you make to 
take effect. 


Cancel changes to 
parameters 


F2— Revert to original 
scheduling 


Causes changes made to return to 
the last scheduled intervals in 
effect. When you use the Alter 
Observer Timing submenu, you’re 
making changes to parameters on a 
“scratch pad.” Select FI to cause 
the changes to take effect. If you 
make changes, then decide not to 
put them in effect, use F2 before 
you use FI to undo the changes 
in the scratch pad. 






The changes you make with FI 
take effect when the status message 
“Node_name acknowledged” 
appears. If you make further 
changes to parameters, then choose 
F2, the logging parameters revert to 
the parameter changes that were 
most recently in effect. 


Get assistance with 
the menu 


F7— Help me use the 
menu 


Gives online help using the menu. 


Exit this menu 


F 8— Return to 
“Change” menu 


Returns to the Change Monitor 
Behavior menu. 



Using the Alter Observer Timing Submenu 

If you attempt to leave the submenu without choosing “Perform Scheduling Changes” or 
“Revert to original scheduling,” an input box prompts “Do you want to perform the 
changes?” [Y | N]. You must choose to perform the change or cancel the change in order 
to leave the menu. 

As shown in Figure A- 10, the rightmost rectangular box on the menu names the observer, 
the middle box displays the observer’s recheck interval and the leftmost box displays the 
observer’s wake-up interval. The wake-up interval (30 minutes by default) is the interval 
at which the observer checks the data it has collected. When an observer reports on a 
node, it does not check data for that node again until after the recheck interval (12 hours 
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by default) . A long recheck interval prevents numerous notifications about the same prob- 
lem. 



A.5.6 The netmain Analyze Network Data Menu 

Use the Analyze Network Data menu to analyze the information netmain__srvr monitors 
collect about your network. This menu enables you to 

• Specify the source of the data you wish to analyze 

• Choose a data output format and appropriate parameters for that format 

• View the data output format on the display monitor or save the display for print- 
ing at a later time 

Figure A- 11 shows the Analyze Network menu, and Table A- 10 lists each command box 
in the menu. 
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Figure A-ll. Analyze Network Data Menu 
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Table A- 10. The netmain Analyze Network Data Menu 



Task 


Command Box Used 


Explanation 


Select a log file 


FI— Network Data 


Brings up a submenu of log files 
you can analyze. If multiple log files 
are specified, netmain merges the 
contents of the files before 
performing the analysis. 


Use data from the 
current monitor 


F2— Network Data 
from monitor 


You must select a monitor with 
FI in the Find Monitors and Nodes 
menu before using this command. 
Data comes from a running 
monitor. To get enough data for 
analysis, use F2 on the Change 
Monitor Behavior menu to set 
probe check intervals to short time 
periods; e.g., 20 seconds. Set the 
time axis marks to about the same 
short intervals. 


Stop data from 
monitor 


F3— Stop data from 
monitor 

i 

■ 


Closes the data stream from a 
running monitor so it can be 
examined from netmain. After 
you issue the command, the 
monitor continues to collect 
data but does not send data to 
netmain. 


Choose a display 
format output 

i 

! 


F4— Display network 
data 

i 


Formats the network data by using 
the output formats you select. You 
cannot display data unless selection 
flags are replaced by some 
performance statistic or output 
format. For most displays, you 
should also choose a topology list, a 
monitor, and a log file. Data is 
displayed in a window that can be 
saved for printing with the DM 
commands pn or pw. CTRL/Q 
halts a display. 


Get assistance with 
the menu 


F7— Help me use the menu 


Gives online help using the 
menu. 


Exit this menu 


F8— Return to Top-Level 
menu 


Returns to Top-Level menu. 
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Using the Analyze Network Data Menu 

Before you can use the Analyze Network Data menu to look at data, you need 

• A source of data. Use one or more log files or a running monitor selected with FI 
in the Find Monitors and Nodes menu. 

® A Topo list. You can use one you’ve already generated with the Find Monitors 
and Nodes menu; or, if you don’t specify a Topo list, netmain will generate one 
to build a display. 

© An Output Format selection. 

After you choose a source of data, the Analyze Network Data menu names the log file(s) 
selected or displays the name of the monitor you are examining. If the log file’s pathname 
is long, netmain truncates it. 

After you have a Topo list and a source of data, select an output format. Netmain displays 
additional menu items containing parameters for that format. Many parameter menu items 
have default selections, others display a “**No Selection* * ” message. When you make a 
selection or change an existing selection, additional menus or prompt boxes can appear. 

After you supply the information necessary, netmain collects the data and generates the 
format you selected. 

The following subsections describe what happens when you choose various command boxes 
from the Analyze Network Data menu. 



Selecting the Log Files Submenu 

Choosing FI Select Log Files produces a menu that lets you analyze one or more of the 
log files you selected with the Find Monitors and Nodes menu. If you choose to analyze 
multiple log files, netmain merges the data from the files. 

Merging multiple log files provides more complete information than using a single log file. 
Several log files may contain data from sequential time periods, for example. Also, if cer- 
tain loops are switched out of the network and there are monitors in each loop, merging 
log files merges the data collected by the monitors on each loop. If you didn’t merge log 
files, you simply would not see data for any loops that were switched out. 

To select each log file, select one of the long, rectangular boxes in the menu and enter the 
log file’s pathname in the input box that appears. The help information that appears lists 
the command search rules netmain uses if you specify a relative pathname. 

If you choose a log file that you haven’t closed, an error message appears. Close the file 
via the Change Monitor Behavior menu or select a working monitor instead. 
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When you analyze more than one log file, enter the log files in any order. If the log files 
were produced by monitors on different nodes, correct any differences between the Univer- 
sal Coordinated Time (UCT) on the nodes running each monitor. If you don’t correct 
these differences, or correct them imprecisely, displays will show numerous “x” marks, rep- 
resenting loss of data. 

UCT differences usually exist only in networks that have multiple monitors. Log files cop- 
ied from one node to another, however, retain the UCT of the node on which they were 
created. 

If you have let the TIME_SKEW probe run, simply select the “FI Compute offset times” 
command to make netmain correct the time differences by using the TIMEJSKEW data. 

If you use the default sampling interval for this probe, the probe will probably have ade- 
quate data to perform the automatic computations. (If it does not have adequate data, the 
computation will fail.) Using the FI command with the TIMEJSKEW probe is the best 
offset time correction method. 

If you have not let the TIMEJSKEW probe run, enter the offset times yourself by using 
the small box at the right of the box that contains the log file name. Find out the UCT 
time on each node from which you’ve chosen a log file. Go to each node, use the date 
shell command, and record the UCT displayed. Be very exact, recording the time it takes 
to walk between nodes and subtracting it from the UCTs you gather. Then, with the times 
written down, choose one node as the node with the “base” UCT. Compute the differ- 
ence (offset) between the base UCT and the UCT on any other nodes from which you’ve 
chosen log files. Enter this offset in the form “+hh:mm:ss” by choosing the offset time 
box and using the input box that appears. 

You can also use the lcnode command to find the times on nodes that run monitors. If 
there are many nodes in the network, take into account the amount of time it takes to 
product the lcnode display. 

If you use the calender utility to reset the UCT on a node running a monitor, there could 
be an offset between log files created before and after you set the UCT. (Note that time 
zone settings do not affect the UCT.) To correct for this offset, manually enter the offset 
between the two times, as just described. Use the old time as a base time, and, for any log 
file created after the calendar reset, enter the new time as an offset of the old time. 



Selecting the Executing Monitors Submenu 

Before selecting an executing monitor as the source of data for a netmain display, re- 
schedule the probes you want to examine to operate more frequently than the defaults. If 
you do not reschedule probes, netmain cannot produce the display until all nodes have 
been sampled at least twice. This can take a very long time with default probe scheduling. 
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A monitor that samples frequently can produce a large amount of data. Ensure that it does 
not reach its maximum size and begin to write over old data. To provide prompt display 
of data, take the following steps: 

1. Use the Change Monitor Behavior menu to close the current log file. Start a new 
log file to record data while you examine the active monitor. 

2. Reschedule the probe (s) you want to examine to check each node every 15 to 60 
seconds. 

3. Use the Analyze Network Data menu to select data from the current monitor. 

4. From the same menu, set the time axis marks equal to the node check interval. If 
the node check interval is 00:00:30, set the time axis marks to 00:00:30. 

5. Use F4 Display Network Data to produce a real-time display of data from the 
executing monitor. 

6. Once you’ve finished examining the data from the executing monitor, type 
CTRL/Q or CTRL/N to stop output to the display. 

7. Use “F3 Stop Data from Monitor”, and return to the Change Monitor Behavior 
menu to reschedule the probes to their original sampling schedule. You can start 
another log file. 

A. 5- 7 Choosing Output Formats for Data 

This subsection describes the output formats available for analysis, the performance statis- 
tics or other data available in each format, and the parameters to specify for each format. 
It also provides additional notes about interpreting output in various formats. 

Netmain provides graphic display output formats, as well as printed and binary data files. 
You can view some kinds of data in several different output formats. 

Choose a format by selecting “Output format selected” in the Analyze Network Data 
menu. 

• Choose a “density plot” format (gray scale plot) to get a graphic display that 
shows the behavior of all nodes. 

• Choose a “peaks” format (scatter plot) to isolate nodes whose behavior on a per- 
formance statistic is above a threshold level. 

• Use an “across net” format to survey nodes’ relative contributions to network- 
wide counts for a performance statistic. 

• Use the “bar chart” format to look at only a single node’s behavior, or to see ex- 
act percentages and counts for a performance statistic. 
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Output Format Descriptions 

Table A-ll lists each of the formats and provides a brief description of each. Use the first 
three formats listed in the table to get information about diskless nodes and network 
events, for example, hardware failure messages. 

Use the other formats listed in the table to display performance statistics collected by net- 
main probes. Performance statistics for the entire network and for individual nodes are 
available in a number of categories. When you select an output format, a menu of pa- 
rameters for that format appears. Use the parameter selection menu to choose a category 
and a performance statistic within that category. (The next subsection, “Output Format 
Parameters” and Table A- 12 describe the parameter menus.) 

In most displays, information about a performance statistic appears as a percentage of a 
total for that category. For example, choosing a performance statistic in the ring transmit 
category shows occurrences of each node’s ring transmit statistics as a percentage of the 
node’s total ring transmits. 

“Rate” and “Across net” formats do not show percentages of node totals in a performance 
statistic category. “Rate” formats, such as “Rate density plot” or “Peak rate” show the 
absolute number of counts per time unit. In “Across net” formats, such as “Density 
across net” or “Peaks across net,” the percentage shown is each node’s contribution to 
network totals for that statistic. 

In the graphs, time intervals appear on the vertical axis. Most of the graphs show data for 
all nodes in the topology list and show the nodes on the horizontal axis. If the topology list 
is empty, netmain performs an lcnode and uses the results. 

Table A- 11 . Output Format Descriptions 



Format 


Description 


Diskless partners 


Displays the network’s diskless nodes and their partners. Configure the 
display to show the diskless nodes served by each “mother” disked 
node, or to show the mother node for each diskless node. Use this 
format only when you analyze data from log files not from executing 
monitors. 


Scattergram events 


Makes a scatter plot of incidences of probe failures or hardware error 
messages. Hash marks represent event incidences higher than a thresh- 
old level set in the parameter menu for this format. 
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Table A— 11. Output Format Descriptions (Cont.) 



Format 


Description 


Bar chart 


Makes a bar chart for the performance statistic you specify in the pa- 
rameter selection menu. Each hash mark (#) in the chart represents 
incidences of the condition tracked by the statistic, as a percentage of 
a total for that statistic. For example, a bar chart for a performance 
statistic in the ring transmit category shows percentages of total ring 
transmits. Unlike other output formats, you can display a perform- 
ance statistic for a single node in a bar chart. For a single node, the 
bar chart shows the statistic as a percentage of a total for that node. 

If you choose “aggregate,” the bar chart shows the statistic as a per- 
centage of a total for the entire network. The bar chart is also the 
only format that provides exact percentage levels and quantities for the 
performance statistic chosen. 


Peak incidences 


Makes a scatter plot of the “peak” incidences of the performance sta- 
tistic chosen. Hash marks represent a percentage of incidences higher 
than a threshold you set for the “Top of error scale” parameter in the 
parameter menu for this format. 


Incidence density 


Makes a gray scale plot that graphically displays the percentage level 
for the performance statistic chosen. The percentage level for each 
node is proportional to the density of the plot. No color represents 
0%, or a percentage too low to report at the resolution set and a solid 
color represents percentages over the ”Top of error scale” number set 
in the parameter menu. The name for this condition is saturation. 


Peak rate 


Makes a scatter plot that shows nodes that exceed a specific threshold 
rate (occurrence per time interval) for the statistic chosen. Hash 
marks represent a rate higher than the threshold set with the “Top of 
rate scale” parameter in the parameter menu for this format. 


Rate density plot 

: 

: 

i 

. 

i 


Makes a gray scale plot that shows, for each node, the rate of occur- 
rence of a condition measured by the performance statistic you select. 
The rate for each node is proportional to the density of the plot. No 
color represents a rate too low to report at the resolution set, and a 
solid color represents rates over the “Top of rate scale” set in the 
parameter menu for this format. The name for this condition is satu- 
ration. 


Peaks across net 




Makes a scatter plot that isolates nodes that contribute the highest 
percentages to network totals for the performance statistic you select. 
Hash marks indicate nodes whose contribution is higher than the 
threshold you set with the “Top of error scale” parameter. 
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Table A- 11. Output Format Descriptions (Cont.) 



Format 


Description 


Density across net 


Makes a gray scale plot that shows the relative contribution of each 
node to network-wide totals for the performance statistic chosen. The 
percentage contribution for each node is proportional to the density of 
the plot. No color represents a contribution too low to report at the 
resolution set, and a solid color represents rates over the “Top of er- 
ror scale” set in the parameter menu for this format. 


Printed output 


Displays a printed summary of events. You can choose to summarize 
incidences of hardware failure messages, user messages, probe failures, 
observer reports, or memory errors. 


Binary data file 

i 

1 


Dumps data into a binary data file that you can use in specialized net- 
work monitoring programs you may wish to write. This format is for 
advanced users who want statistics not provided by netmain. See the 
insert file /sys/ins/nud.ins.pas for the binary file record structure, and 
see the files /domain_examples/netmain/nud_example.pas or /do- 
main_examples/netmain/nud_example.ftn for an example of how to 
use it. 



Output Format Parameters 

When you select an output format, a menu of appropriate parameters for that format ap- 
pears. The menu items are identical for many output formats. Table A- 12 describes each 
parameter and shows the output formats for which it is required. 

Table A-12. Parameters for Output Formats 



Parameter 


Required By These 
Output Formats 


Parameter Function 


Select a log file 


FI— Network data from log 
files on the Analyze 
Network Data menu 


Brings up a menu of log files that 
you can analyze. If multiple log 
files are specified, netmain 
merges the contents of the files 
before performing the analysis. 
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Table A-12. Parameters for Output Formats (Cont.) 



Parameter 


Required By These 
Output Formats 


Parameter Function 


Earliest/Latest data 
displayed 


All, when you use these 
files for analysis 


Lets you limit the time range 
over which errors are reported, 
when you’re using log files for 
analysis instead of a monitor. 




None, when you use a 
monitor 


By default, reports start with the 
earliest data “First in log” and 
end with the latest “Last in log.” 
To shorten the time range, enter a 
later time in the prompt box when 
you choose earliest data displayed, 
or enter an earlier time in the 
prompt box when you choose latest 
data displayed. 


Time axis marks 


All, except “Printed output” 
and “Diskless partners” 


Lets you change the length of the 
time units used in formatted data 
outputs. 


Max wait for data 

. 


Same as above; also not 
necessary when you select 
“bar chart” with actual 
sampling times 


Sets the number of time axis 
intervals that netmain will wait 
for data from a missing node. 

After the specified time, netmain 
continues to format data. When 
you are analyzing data from a log 
file, you can enter “end-of-file” to 
read to the end of a log file before 
continuing with the scattergram. 
You cannot choose “end-of-file” 
when you are examining an 
executing monitor. 


Top of error scale 


“Bar chart” “Density 
across net ” 


Sets the full-scale value or the 
threshold used in the output 
format you’ve chosen. In gray 
scale plots, incidences higher 
than the value set cause saturation, 
so the value you set is a full-scale 
value. In scatter plots, incidences 
higher than the value set show as 
hash marks, so the value you set is 
a threshold. 
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Table A-12. Parameters for Output Formats (Cont.) 



Parameter 



Data plotted 



Data dumped 



Events plotted 



Data printed 



Data ordering 



Required By These Parameter Function 



Output Formats 



“Bar chart” “Density 
across net ” 



Binary data file” 



Scattergram events” 



Printed output” 



Diskless partners” 



The value set is given in percent 
units or, for rate plots, as a ratio 
of counts per time unit). The 
meaning of the percent unit 
depends on the format. For output 
formats that only show levels for 
performance statistics, the value is 
percentage of the total that results 
this condition. For “across net” 
formats, the value is the percent 
that each node contributed to the 
total number of errors of that type 
over the time interval. The default 
value is 50%. 

Specifies the data value you see in 
plots and scattergrams. Displays a 
submenu (or peaks) from which 
you choose one of the categories 
shown in Table A-ll. See Section 
A. 4 for information about specific 
performance statistics. 

Specifies data as in “data plotted,” 
above. Here, however, netmain 
sends data to a binary file instead 
of formatting it for screen display. 

Lets you create a scattergram of 
hardware failure messages or 
probe failures. See Section A. 4 for 
information about these events. 

Lets you choose printed reports 
on hardware failure messages, 
probe failures, user messages, or 
memory errors. 

Lets you specify whether the 
“Diskless partners” format shows 
diskless nodes for each diskless 
node (choose “Partners by 
Diskless”.) 
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Table A-12. Parameters for Output Formats (Cont.) 



Parameter 


Required By These 
Output Formats 


Parameter Function 


Node to plot for 


“Bar chart” 


Displays an input box that lets 
you specify the name of the 
node for which statistics are 
displayed in a bar chart. By 
default, the chart shows the 
sum for all nodes (network 
aggregate). 



Interpreting Bar Chart Displays 

The left section of a bar chart contains four columns of information about each time inter- 
val. The time and date that each interval ended are in the far left columns. The actual 
number counted for the performance statistic during this interval, and the number as a 
percentage of a total for the performance statistic, are in the next two columns. Netmain 
rounds off percentages to the nearest integer value. Each hash mark (#) represents a part 
of this percentage. 

The actual percentage represented by one hash mark depends on on the scale you choose 

for the graph, using “Top of scale.” This value is the full-scale value of the bar 

graph. With a full-scale value of n percent, the bar graph is at its maximum or full-scale 
length (50 hash signs) when n percent of the transmit or receive I/O operations result in 
the error selected. If you use the default value of 50 percent, then the bar graph contains 
50 hash signs when 50 percent of the operations result in the error selected. Using the 
default, then, each hash sign stands for a percentage of 1 percent. 

If a node has been rebooted or if a probe has failed because of a transmit failure, the plot 
reports the reboot or transmit failure during the time interval in which it occurred. A set of 
greater-than (>) characters to the right of the hash marks indicates that the graph is off 
scale. Make the “Top of error percentage scale” higher if this problem occurs. 

When you choose to plot for a single node, you should set the time axis intervals to corre- 
spond to the node's check intervals. This prevents inaccuracies due to the skewing between 
check intervals and time axis intervals. 

When you interpret an aggregate plot, be aware of the limits on the plot’s resolution. The 
node check intervals determine the resolution of the data. A check interval of 1 minute 
will of course produce higher resolution data than a check interval of 30 minutes, but you 
may be using a check interval of 30 minutes because of log file size limitations. Whatever 
your check interval, try to set the time axis interval in your aggregate plots to about the 
same number. Then, when you interpret the plots, note that displays may spread the error 
incidences out over a period of roughly two check intervals. 
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For example, if the check interval is 30 minutes and a 2-minute period of network prob- 
lems occurs, many nodes may not be sampled until up to a half hour after the 2-minute 
period. Instead of showing a peak for a 2-minute period, the errors could be spread out 
over a 1-hour period. 

If the time axis interval is much longer or much shorter than the check interval, the dis- 
plays will be skewed even more and will pinpoint peak times for a particular performance 
statistic less accurately. If the check interval is much longer than the time axis interval, 
the times reported will be very inaccurate. 

When a node is rebooted, it resets all its internal counters. The counts for a time axis 
interval during which a node was rebooted include only those statistics counted after the 
reset. The counters lose any quantities counted in the time axis interval before the reset. 
For this reason, time axis intervals which include node rebootings can report an artificially 
low incidence for the statistic. Charts for single nodes can show “node rebooted” messages 
in place of a report for that time interval. 



Interpreting Scatter and Gray Scale Plot Displays 

Scatter plots for hardware or probe failures illustrate incidences of each of these events 
with an n or asterisk (*), where n is an integer between 1 and 9, and the asterisk repre- 
sents any integer greater than 9. Plots for performance statistics show any failure to get 
information from a node as an x. 

Peak times shown in scatter plots have the same resolution limitations that they do in bar 
graphs (discussed in the previous subsection). Also, you should ignore the first line in a 
scatter plot since it usually shows an incomplete time axis interval. 

If your network is very large, with more than 225 nodes, and you attempt to create a plot 
showing all nodes, the Display Manager (DM) cannot display the rightmost columns in the 
display for each time interval. To avoid this problem and display all nodes, take the 
following steps: 

1. Take the total node list from the monitor and display it, using the Find Monitors 
and Nodes menu. 

2. Use the DM to cut and paste the list into a new file. 

3. Edit the new file to give it a format acceptable to the “Topo list from data file” 
command. See netmain help for details on this command. 

4. Now cut and paste part of this new file into a separate file. You should now have 
two files, each containing a list of half the nodes on the total node list. 

5. Invoke the “Topo list from data file” command and name the first file. Then do 
a plot. 
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6. Now invoke the “Topo list from data file” command again; this time name the 
second file. Now do another plot. 

7. You now have plots in two windows, each containing half of the nodes. You can 
line the two windows up by using DM window control commands so that the two 
windows give the effect of one very large window. 



Saving Output Displays 

You will often want to save netmain displays for future reference. When it makes a dis- 
play, netmain creates a window and a pad, writes the text into the pad using special fonts, 
and closes the pad. You can save the pad in the fonts used by using the pn (pad name ) 
command. Position the cursor in the window, then type the following command: 



pn filename 

Filename must be a file on your node. When you close the window in which netmain pro- 
duced the display, (with CTRL/Y), the filename will contain the display in the original 
fonts. If you just cut and paste to a file, the special fonts will not be used, and the text 
may be less easy to read. 

To print one of these saved files, open the file using <READ> or <EDIT>. Then use the 
cpscr shell command to make a copy of the entire screen display and store it in a second 
file. Print the file with the -plot option. You can use the following command sequence: 



cpscr second Jilename\ prf second_filename -plot 

See the SysV, BSD , or Aegis Command Reference manual for more information about the 
prf and cpscr commands. 



gg 
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/alarm_server.msg_mbx file, 3-41 

B 

Bourne shell, 3-28 

/bin directory, and system type environment 
variable, 3-7 
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bit-pad support. See tablet server. 



C 

C shell, 3-28 

cancel command, 6-2 
function, 6-10 

case sensitivity 
and the DM, 3-28 
and the spm, 3-28 

case sensivity, and SR10, 1-2 

cataloging a node 
displayless, 2-6 to 2-7 
general, 2-3 

in a root directory, 2-4, 2-5 
in an existing network, 2-9 

chad command, 5-11, 5-13 

chgrp, 5-4 

child processes. See siomonit and child proc- 
esses 

chmod, 5-4 

chmod command, 5-13 

chown, 5-4 

clocks. See node clocks, 
cp command 

and starting server processes, 3-14 
context inheritance, 3-11 

cpo command 

and starting server processes, 3-14 
context inheritance, 3-11 

cps command 

and starting server processes, 3-14 
context inheritance, 3-11 

creat system call, 5-4 
crl command, 3-7 
crp command, 3-6 
ctnode command, 2-3, 2-8 
cvtrgy, 4-3 

D 

Devconfig file, 7-7 
entry format, 7-26 



use, 7-25 

Devices file, 7-7 
Class field, 7-9 

dialer-token-pairs field, 7-9 to 7-11 

entry format, 7-8 

line field, 7-8 

line2 field, 7-9 

type field, 7-8 

use, 7-7 

Dialcodes file, 7-7 
entry format, 7-17 to 7-18 
use, 7-17 

Dialers file, 7-7 
entry format, 7-12 
escape characters, 7-12 to 7-13 
handshake, 7-13 
penril entry, 7-13 
use, 7-11 to 7-12 

Display Manager. See DM 

DM, context inheritance, 3-11 

DM startup, 3-21 to 3-53 

Domain Professional Mail Services. See 
DPSS/Mail 

Domain Server Processors 
See also displayless nodes, 
defined, 3-12 

Domain/OS environments, selecting, 3-16 

DPSS/Mail 
and Alis, 2-39 
and sendmail, 2-39 
and UNIX gateway, 2-38 
defined, 2-38 

DSP. See displayless nodes 

DSPs. See Domain Server Processors 

directories 

‘node_data, 3-9 to 3-10 
upper-level, 3-3 

directory 
node entry, 3-3 
root, 3-3 

top-level. See root directory 
volume entry, 3-4 

directory names, 3-1 

disable command, 6-2 
example, 6-11 
function, 6-11 

diskless node 

initialization procedure, 3-29 
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paging partner, 3-35 
partner requirements, 3-29 
warning of partner shutdown, 3-35 

diskless nodes 

assigning partners, 3-30 to 3-53 
configuring partners for, 3-31 to 3-34 
listing names of, 2-18 
name assigned by edns, 2-17 
naming on existing network, 2-17 
problems communicating with partner, 3-35 
requesting a specific partner, 3-35 to 3-36 

diskless_list file, 3-30 to 3-34 

displayless nodes, cataloging, 2-6 to 2-7 

dll command, 3-7 

dm/startup_templates directory, 3-28 



edacl command, 5-11, 5-13 
edns 

adding node to master root directory, 2-26 to 
2-27 

commands, 2-15 to 2-16 
defined, 2-12 

deleting names from master root directory, 
2-27 

name assigned to diskless nodes, 2-17 
permissions, 2-19 

replacing node information in the master root 
directory, 2-29 

edrgy, 4-2 

managing names and accounts, 4-16 

enable command, 6-2 
example, 6-11 
function, 6-11 

ENVIRONMENT value, 3-17 

/etc/daemons file, 3-20 

/etc directory, and system type environment 
variable, 3-7 

/etc/group file, 4-10 

/etc/mknod command, 3-3 

/etc/mtab, 3-4 

/etc/org file, 4-10 

/etc/pass wd file, 4-10 

/etc/rc. local file, 3-20 



/etc/rc.user file, 3-20 
/etc/server command, 3-14 

F 

file names, 3-1 



G 

getty, requirement for uucp, 7-3 
glbd. See global location broker daemon 
global location broker daemon, 4-3 

H 

home directories, 3-12 

I 

import_passwd, 4-3 
/etc/syncids tool, 4-36 
command syntax, 4-35 
favored entry option, 4-33 
identical user option, 4-33 
name conflicts, 4-31 
prompts, 4-36 

UNIX ID Conflicts, 4-31, 4-33 
init program, 3-18 

invol, creating and maintaining logical volumes, 
3-3 



K 

key definitions, 3-25 

L 

Location Broker, 4-1 

line printer system 
configuration, 6-2 
defined, 6-1 
files and directories, 6-3 
functions, 6-1 

interface programs. See printer interface pro- 
gram 
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lpfilter, 6-15 

ownership of commands and files, 6-2 
scheduler. See lpsched 

links 

symbolic, 3-7 
variant, 3-7 

llbd. See local location broker daemon, 

In command, 3-7 

local location broker daemon, 4-3 

local registries, 4-1 

local registry, 4-43 
edrgy -1 command, 4-43 

location broker 

global location broker daemon (glbd) , 4-3 
local location broker daemon, 4-3 

locksmith, 4-7 

log files, 3-10 

log-out processing, 3-25 

logical volume 

mounting on a diskless node, 3-4 3-5 
sample block files, 3-4 

logical volumes 

block files created at installation, 3-3 
general, 3-3 
mounting, 3-4 
unmounting, 3-4 

login monitoring 

and configuration file protection, 3-52 
and log file, 3-52 

and log file protection, 3-52 to 3-53 

general, 3-51 

specifying log file, 3-51 

specifying the login type to monitor, 3-5 1 

login Jog file, 3-51 

login Jog. cofig file, 3-51 

lp command, 6-2 
examples, 6-9 
function, 6-2, 6-8 

lp system. See line printer system 

lpadmin command, 6-2 
adding new device examples, 6-5 
and printer interface program, 6-14 
changing default print destination example, 
6-8 

modifying printer configuration example, 6-6 
to 6-7 



removing destination example, 6-8 

required options, 6-4 

use to change default destination, 6-7 

lpfilter, 6-15 

lpmove command, 6-3 
examples, 6-11 to 6-12 
function, 6-11 

lpsched command, 6-2 
checking status, 6-13 
executing at system start, 6-4 
function, 6-2, 6-12 
log file contents, 6-12 
starting, 6-12 to 6-13 
stopping, 6-13 

lpshut command, 6-2 
lpstat command, 6-9 
lsacl-1 command, 5-12 

M 

Maxuuscheds shell script, 7-5 

Maxuuxgts shell script, 7-5 

master registry, changing site of, 4-22 

master registry server 
adding names and accounts, 4-14, 4-15 
establishing uniform UNIX numbers, 4-14 
starting, 4-14 

master root directory, 2-12 
adding nodes to, 2-26 to 2-27 
deleting names from, 2-27 
replacing node information in, 2-29 

mbxjielper 
and ACLs, 3-42 
general, 3-41 to 3-42 

membership list, 4-6 
mount command, 3-4 
mtvol command, 3-4 

N 

naming tree, 3-1 
netmain interactive tool, 3-35 
netmain_srvr, 3-35 
netman, 3-29 

and new diskless node partners, 3-30 
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bypassing diskless_list, 3-43 
function, 3-42 

starting, from DM command line, 3-42 to 
3-43 

starting, general, 3-42 
stopping, 3-43 

network, creating, 2-9 

' network configuration 
access control, 7-2 
distance between systems, 7-3 
hardware considerations, 7-3 

network registry, 4-1 

node 

cataloging 

displayless, 2-6 to 2-7 
general, 2-3 

in a root directory, 2-4, 2-5 
in an existing network, 2-9 
changing ID or UID and node name associa- 
tions, 2-18 

communicating with hung node, 3-36 

IDs, 2-2 

name 

assigning, 2-2 
changing, 2-10, 2-28 
default, 2-3 

deleting from root and master root directo- 
ries, 2-18 

updating information for, 2-10, 2-11 
start-up file summary, 3-26 
start-up file types, 3-26 to 3-27 
start-up process, 3-18 to 3-26 
startup file templates, 3-27 to 3-28 
troubleshooting, 3-36 to 3-37 
when to catalog, 2-3 

node access, controlling with ‘node_data/ 
spm_control, 3-21 to 3-23 

node clocks 
checking, 2-31 

synchronizing, 2-17, 2-20 to 2-21 

• node entry directory, 3-3 

node software structure, 3-7 to 3-9 

node_data [ .node_id] /startup_login [ .type] file, 
3-25 

nodes, defined, 1-1 
ns_helper 

and synchronizing clocks, 2-17 
cataloging nodes, 2-3 to 2-14 



checking replica node clocks, 2-31 
database 

changing name, 2-15 
contents, 2-13 

initialization procedures, 2-24 to 2-25 
function, 2-12 
replica database, 2-12 
creating, 2-30 

maintaining consistency of, 2-32 to 2-33 
removing, 2-34 to 2-35 
shutting down, 2-35 
replica list, 2-12, 2-14 to 2-38 
running multiple, 2-13 to 2-14 
starting, 2-12 

starting procedures, 2-22 to 2-23 
when to initialize, 2-17 
when to use, 2-13 



P 

Permissions file, 7-2, 7-7 
CALLBACK option, 7-21 to 7-22 
COMMANDS option, 7-22 
entry format, 7-18 
LOGNAME entry, 7-18, 7-25 
MACHINE entry, 7-18, 7-25 
NOREAD and NO WRITE options, 7-21 
READ and WRITE options, 7-20 to 7-21 
REQUEST option, 7-19 to 7-30 
restricting access levels for remote logins, 
7-19 

SENDFILES option, 7-19 to 7-20 
use, 7-18 

VALIDATE option, 7-23 to 7-24 

Poll file, 7-7 
entry format, 7-25 
use, 7-25 

use to poll other systems, 7-28 
PROJLIST, 5-4 

paging partner. See diskless node, paging part- 
ner 

passwd command, 7-2 

password, 4-6 
/etc/passwd, 4-5 

password file, 7-6 
administrative login, 7-6 
sample entry, 7-6 

password, encrypted, 4-5 
pathnames, 3-1 
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permissions 
/etc/group file, 5-3 
/etc/passwd file, 5-3 
group, 5-3 

locksmith group, 5-15 

newgrp command, 5-3 

others, 5-3 

owner, 5-3 

root person, 5-15 

special groups and accounts, 5-15 

staff, 5-15 

super-user, 5-4 

sys_admin, 5-15 

using open system call, 5-4 

wheel groups, 5-15 

with mode argument, 5-4 

physical volumes, 3-3 

prf command, and printer interface program, 
6-14 

print destination 
defined, 6-2 

establishing routing, 6-10 

steps to determine destination, 6-8 

print destinations 
creating new, 6-4 to 6-5 
default, 6-7 

disallowing print requests, 6-10 
modifying, 6-6 
removing, 6-7 to 6-8 

print requests 
canceling, 6-7, 6-10 
moving to another destination, 6-7 

printer 

disabling. See disable comand 
enabling. See enable command 
vs. printing device, 6-1 

printer class 
adding a printer to, 6-5 
defined, 6-1 
removing, 6-7 to 6-8 

printer interface program 
device filters, 6-14 to 6-15 
formatting, 6-16 
function, 6-13 
input and output, 6-14 
invoking, 6-13 to 6-14 
lpfilter, 6-15 
prf support, 6-14 
return codes, 6-16 
terminal characteristics, 6-16 



printing device, defined, 6-1 

processes, checking ones running on a node, 
3-37 

protection, of registry database, 5-18 

protection modes 
UNIX Is -1 command, 5-2 
UNIX mode, 5-2 

protocols. See uucp, protocols. 

ps command 

and displaying server processes, 3-15 

use to check status of server processes, 3-16 

pst command, and bit-pad process, 3-44 

R 

rc file 

access rights assigned to servers, 3-19 
and /etc/daemons, 3-20 
functions, 3-19 

use during start-up processing, 3-18 
registry, 4-1 

master registry node, 4-1 
normal node, 4-1 
registry database, 4-2 
registry server, 4-1 
replica registry node, 4-1 
rights of owners, 4-8 
troubleshooting problems, 4-25 

registry copy, 4-12 
/sys/registry, 4-12 

registry database 
accounts, 4-3 

backing up procedure, 4-18 
configuration, 4-13 
creation of, 4-13 
fullnames, 4-4 
names, 4-3 
aliases, 4-4 
primary names, 4-4 
ownership information, 4-8 
policies, 4-3 
properties, 4-8 

setting up a new SR 10 registry, 4-14 
subject identifiers, 4-5 

registry replica, delrep -force command, 4-30 
registry replicas 

creating slave registry replicas, 4-15 
propagating changes to, 4-21 
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registry replication 
propagation queue, 4-11 
replica list, 4-11 
update, 4-12 

registry server, /etc/rgyd, 4-2 

registry servers, /etc/daemons/rgyd, 4-20 

regy__ admin, 4-16 

reject command, 6-3, 6-10 
example, 6-10 

remote. unknown shell script, 7-5 

replica list. See ns_helper. 

resistry, and SR10, 1-2 

rgy_admin, 4-3 
lrep -state command, 4-26 

rgy_merge t 4-3 

rgyd, 4-20 

rm command, 3-7 

root directory, 3-3 
defined, 2-1 



S 

sbpl. See tablet server. 

send_alarm command, 3-35 

sendmail command 
arguments, 8-4 
configuration options, 8-4 
mailer flags, 8-4 

sendmail configuration, 8-2 
address rewriting rules, 8-3 
building from scratch, 8-25 
building mailer descriptions, 8-27 
large site, 8-25 
single host, 8-26 
small site, 8-26 
testing rules, 8-27 
configuration file, 8-15 
semantics, 8-18 
syntax, 8-15 
header declarations, 8-3 
macros, 8-3 
mailer declarations, 8-3 

sendmail configuration parameters, 8-13 
delivery mode, 8-14 
file modes, 8-14 
log level, 8-14 



timeouts, 8-13 

sendmail facility, 8-1 

sendmail installation, 8-3 
sample configuration files, 8-4 

sendmail interfaces, 8-2 
argument vector/exit status, 8-2 
SMTP over an IPC Connection, 8-2 
SMTP over pipes, 8-2 

sendmail operation 
.forward files, 8-12 
Alias Database, 8-11 
mail queue, 8-9 
forcing the queue, 8-10 
mail queue command, 8-9 
queue file format, 8-9 
special header lines, 8-12 
apparently-to, 8-13 
errors-to, 8-13 
return-receipt-to, 8-12 
system log, 8-8 
levels, 8-8 

sendmail rewriting rules 
left-hand side, 8-21 
mailer flags, 8-24 
recipient address rules, 8-22 
right-hand side, 8-21 
sender address rules, 8-23 

sendmail support files, 8-29 

sendmail, introduction, 8-1 

server Group, 5-15 
/etc/server, 5-15 
cps command, 5-15 

server processes, and ACLs, 3-16 

server process, stopping, 3-16 

server process, and shell command-line fea- 
tures, 3-16 

server processes, 3-14 
and DSPs, 3-12 
and spm, 3-14 
checking status of, 3-16 
defined, 3-12 
displaying status, 3-15 
functions, 3-13 
help command, 3-37 
naming, 3-15 to 3-16 
number to implement, 3-12 to 3-13 
start-up method summary, 3-15 
starting as user. server. none. See /etc/rc.user 
file 

starting as root, wheel. none. See /etc/rc file 
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starting in /etc/rc, etc/rc.user, and /etc/rc.tcp, 
3-14 

starting with cp, cps, and cpo commands, 

3-14 

starting without using the DM, 3-14 

server processors, location, 3-13 

Server Process Manger. See spm. 

setgid bit, 5-3 

setuid bit, 5-3 

shutspm command 
default ACLs, 2-37 
function, 2-36 

sigp command, use to stop server processes, 

3-16 

SIO line servers. See /etc/ttys file; siologin and 
siomonit 

SIO lines 
configuring, 3-46 

connecting terminals to workstations, 3-44 to 
3-45 

freeing locked lines, 3-50 
startup, 3-22—3-23 

siologin, 3-23 
and remote access, 3-46 
and required status, 3-47 
and unsucessful login attempts, 3-46 to 3-47 
configuring lines, 3-46 
function, 3-44 
operation, 3-45 
options, 3-46 
requirement for uucp, 7-3 
syntax, 3-45 

siologin__access file, 3-46 

siologinjog file, 3-46 

siomonit, 3-23 

and child processes, 3-47, 3-50 
function, 3-44, 3-47 
log files, 3-49 to 3-50 
operation, 3-47 
restarting, 3-48 

signaling to reread argurment file and re-exe- 
cute, 3-48 

siomonit _file, 3-48 to 3-49 
somonit_file, 3-48 

starting from DM command line, 3-48 
starting from start-up file, 3-48 
stopping, 3-48 

use to free locked lines, 3-50 



siomonit_file. See siomonit. 

software protection, invol utility, 5-18 

spm 

and server processes, 3-14 
function, 2-36 

starting from /etc/rc file, 2-36 
starting from DM command line, 2-36 
stopping, 2-36 to 2-37 

spm (Server Process Manager), stopping with 
shutspm. See See also shutspm command 

spm startup, 3-21 to 3-23 
spm/startup_templates directory, 3-28 
spm_control file, 3-21 to 3-23 
spmshut_ec file. See See shutspm command 
spooling functions. See line printer system 
startup__login[.type] file, 3-25 
startup_logout[.type] file, 3-25 
startup_sio.sh file, 3-46 
strace command, 2-38 
strclean command, 2-38 

STREAMS 
defined, 2-37 

error logging commands, 2-38 
streamd daemon, 2-38 
streer command, 2-38 
Sysfiles 

entry format, 7-26 
example, 7-27 
use, 7-26 

System Administrator, responsibilities, 1-1 

Systems file, 7-2, 7-7 
class field, 7-15 
entry format, 7-14 
login field, 7-16 to 7-17 
phone field, 7-15 to 7-16 
system-name field, 7-14 
time field, 7-14 to 7-15 
type field, 7-15 
use, 7-14 

systype variable, 3-17 

T 

TCP/IP, starting. See rc.tcp file 
tablet server 

checking bit-pad process, 3-44 to 3-45 
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function, 3-43 
starting, 3-44 

temporary files, 3-10 
top-level directory. See root directory 
touch command, 5-4 
ttys file 

and DM startup, 3-21 
and SIO line startup, 3-22 to 3-23 
and spm startup, 3-21 to 3-23 
and window system startup, 3-22 
general, 3-20 

U 

UID (unique identifier), 4-4 
UNIX number, 4-4 
UNIX protection mechanism, 5-10 
Uutry shell script, 7-5 

uctnode command, 2-8 
and ns_helper, 2-15 
cataloging nodes, 2-3 

umask command, 5-4 

unmount command, 3-4 

upper-level directories, 3-3 
creating, 3-12 

use as application libraries, 3-12 
use to manage system resources, 3-11 

user login process, 3-23 to 3-25 

/usr directory, and system type environment 
variable, 3-7 

~/user/startup_dm[.type] file, 3-25 

~/user_data/alarm_server.msg_mbx file, 3-41 

uucheck command, 7-4 

uucico daemon, 7-3, 7-4 
use to verify system on network, 7-29 

uucleanup command, 7-4 

uucp 

See also Devconfig file; Devices file; Dialcodes 
file; Dialers file; Permissions file; Poll file; 
password file.; Sysfiles file; Systems file 
Apollo configuration, 7-5 
administrative login, 7-6 
administrator’s tasks, 7-27 
and getty, 7-3 
and siologin, 7-3 



cleanup, 7-27 

dialers supported, 7-3 

escape characters, 7-17 

examining log file contents, 7-29 to7-30 

identifying bad ACUs and modems, 7-28 

interconnection methods, 7-2 

maintenance considerations, 7-3 

modules installed, 7-4 

networks supported, 7-3 

operation, 7-3 

out of space problems, 7-28 

polling other systems, 7-28 

protocols, 7-11 

shell scripts, 7-5 

uucp command, 7-3, 7-4 
in Apollo configuration, 7-5 

uucp directory, contents, 7-7 

uudemon. admin shell script, 7-5 

uudemon. cleanup shell script, 7-5 
use to cleanup undeliverable jobs, 7-27 

uudemon. hour shell script, 7-5 

uudemon.poll shell script, 7-5 
and Poll file, 7-25 

uulog shell script, 7-5 
uuname command, 7-4 
uupick shell script, 7-5 
uusched command, 7-4 
uustat command, 7-4 
uuto shell script, 7-5 

uux command, 7-3, 7-4 
in Apollo configuration, 7-5 

uuxqt daemon, 7-4 

V 

variant link, 3-7 
volume entry directory, 3-4 

W 

wall command, 3-35 
window system startup, 3-22 
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